Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
215 changes: 215 additions & 0 deletions apps/36-blocks/src/app/ai-setup/ai-prompts.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
/**
* Prompt builders for handing 36Blocks setup to the user's own AI coding agent.
*
* The agent signs in through the 36Blocks MCP server's browser authorization (OAuth), so no prompt ever carries a
* credential, token, secret, key or block reference id. Everything the agent needs it reads through the connector.
*
* Rules:
* - Keep prompts short and point at the public docs for detail.
* - Values embedded in a prompt (the block name, a reference id) are validated first, so nothing unvalidated can inject
* instructions.
* This file is deliberately dependency-free so it can be unit tested without Angular.
*/

export const LLMS_TXT_URL = 'https://developers.36blocks.com/llms.txt';
export const MCP_SERVER_URL = 'https://mcp.docstar.io/connector/36blocks_user_api';
/** Name used when registering the MCP server in a tool. */
export const MCP_SERVER_NAME = '36blocks';
export const CLI_INIT_COMMAND = 'npx docstar-cli init 36blocks_user_api';
export const CLI_RUN_HINT = 'npx docstar-cli 36blocks_user_api <module> <endpoint> [--flags]';
export const CLI_LIST_COMMAND = 'npx docstar-cli list 36blocks_user_api';

export type AiPromptKind = 'general' | 'block' | 'setup';

export interface BlockPromptContext {
/** The block's `reference_id` (public identifier, not a secret). */
referenceId: string;
/** Human block type, e.g. "Authorization". Optional: omitted when the page does not know it. */
blockType?: string | null;
/** Widget script `type` for the block, e.g. "authorization". Optional. */
widgetType?: string | null;
/** URL of the widget script (`proxy-auth.js`). Optional. */
scriptUrl?: string | null;
}

const REFERENCE_ID_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
const LABEL_PATTERN = /^[A-Za-z0-9 _-]{1,40}$/;

export function isValidReferenceId(value: unknown): value is string {
return typeof value === 'string' && REFERENCE_ID_PATTERN.test(value);
}

function safeLabel(value: unknown): string | null {
return typeof value === 'string' && LABEL_PATTERN.test(value.trim()) ? value.trim() : null;
}

function safeHttpUrl(value: unknown): string | null {
if (typeof value !== 'string') return null;
try {
const url = new URL(value);
return url.protocol === 'https:' || url.protocol === 'http:' ? url.toString() : null;
} catch {
return null;
}
}

// ---------------------------------------------------------------------------------------------------------------------
// Block name
// ---------------------------------------------------------------------------------------------------------------------

export const BLOCK_NAME_MIN = 2;
export const BLOCK_NAME_MAX = 60;
/**
* The server rule is `^[a-zA-Z0-9][a-zA-Z0-9_\s]+$`. `\s` also matches tabs and line breaks, which must never reach a
* prompt, so only plain spaces are accepted here (a strict subset of the server rule).
*/
export const BLOCK_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_ ]+$/;

export type BlockNameProblem = 'required' | 'too-short' | 'too-long' | 'characters';

export interface BlockNameCheck {
valid: boolean;
/** The trimmed name; only meaningful when `valid`. */
value: string;
problem: BlockNameProblem | null;
}

export function checkBlockName(raw: unknown): BlockNameCheck {
const value = typeof raw === 'string' ? raw.trim() : '';
const fail = (problem: BlockNameProblem): BlockNameCheck => ({ valid: false, value, problem });
if (!value) return fail('required');
if (value.length < BLOCK_NAME_MIN) return fail('too-short');
if (value.length > BLOCK_NAME_MAX) return fail('too-long');
if (!BLOCK_NAME_PATTERN.test(value)) return fail('characters');
return { valid: true, value, problem: null };
}

export function blockNameMessage(problem: BlockNameProblem | null): string {
switch (problem) {
case 'required':
return 'Enter a name for the block.';
case 'too-short':
return `Use at least ${BLOCK_NAME_MIN} characters.`;
case 'too-long':
return `Use at most ${BLOCK_NAME_MAX} characters.`;
case 'characters':
return 'Start with a letter or number. Use only letters, numbers, spaces and underscores.';
default:
return '';
}
}

// ---------------------------------------------------------------------------------------------------------------------
// Prompts
// ---------------------------------------------------------------------------------------------------------------------

const CONNECT_LINES = `To run the APIs, prefer the MCP server: ${MCP_SERVER_URL}
When it asks you to sign in, finish the 36Blocks sign-in and approval in the browser. Don't ask me to paste a key, token or reference id.

If you can't connect MCP, use the CLI instead (run once to install the modules): ${CLI_INIT_COMMAND}
Then: ${CLI_RUN_HINT} (${CLI_LIST_COMMAND} shows what's available)`;

/**
* Widget login needs no auth key. The key only exists for server-to-server calls, and it must reach the app through the
* user's own environment file: never through the chat and never into code.
*/
const AUTH_KEY_RULE = `Widget login needs no auth key. Only if my app makes server-to-server calls with one, tell me to copy it from Team & access → API keys in the 36Blocks panel into my own environment file, and say which variable you read it from. Never ask me to paste it into this chat and never write its value into code.`;

/** The block holds one redirect URL, so it should be the production one; other environments have two clean options. */
const REDIRECT_RULE = `The block's redirect URL is the production URL of the app (where signed-in users land, for example https://app.example.com/auth/callback). If I haven't deployed yet or you can't tell, ask me, and use the local URL meanwhile. For localhost or staging, suggest a separate block for that environment (ask me before creating it), or pass addInfo.redirect_path in the widget config so the redirect stays on the page's own origin.`;

/** The homepage prompt: MCP first, with the browser sign-in done by the user, never a pasted credential. */
export function buildGeneralIntegrationPrompt(): string {
return `Integrate 36Blocks User APIs into our project based on our requirement and use cases.
First, read the official API documentation at ${LLMS_TXT_URL}.
Ask what I want to build if I haven't explained it yet.

${CONNECT_LINES}

If we need a new login block, create it yourself with the Create Login Block (Simple) tool (create_login_block) once I've approved the sign-in. ${REDIRECT_RULE}

${AUTH_KEY_RULE}`;
}

/** For one specific, existing block. Returns null when the block's reference id is not a plain identifier. */
export function buildBlockIntegrationPrompt(context: BlockPromptContext): string | null {
if (!isValidReferenceId(context?.referenceId)) return null;
return blockPromptBody(context, CONNECT_LINES);
}

function blockPromptBody(context: BlockPromptContext, transport: string): string {
const blockType = safeLabel(context.blockType);
const widgetType = safeLabel(context.widgetType);
const scriptUrl = safeHttpUrl(context.scriptUrl);

const details = [`Block reference_id: ${context.referenceId}`];
if (blockType) details.push(`Block type: ${blockType}`);
if (widgetType) details.push(`Widget type: ${widgetType}`);
if (scriptUrl) details.push(`Widget script: ${scriptUrl}`);

return `Integrate an existing 36Blocks block into our project. Don't create a new block.
${details.join('\n')}

First, read the official API documentation at ${LLMS_TXT_URL}.
Ask which app or framework this is for if I haven't said. Read the block's settings (login methods, redirect URL, allowed origins) with the Get Block tool (get_block) and its widget snippet and redirect behaviour with Get Block Integration Details (get_block_integration). Change settings only with Update Login Block (update_login_block), and tell me what you change.

${transport}

${REDIRECT_RULE}

${AUTH_KEY_RULE}`;
}

// ---------------------------------------------------------------------------------------------------------------------
// The setup wizard prompt
// ---------------------------------------------------------------------------------------------------------------------

export interface SetupPromptInput {
/** Name of the block to create. Validated with `checkBlockName`. */
blockName: string;
}

/**
* The wizard prompt: the agent connects the 36Blocks MCP server, completes the browser sign-in, creates one block with
* the given name, configures the login method and redirect URL for the user's app, and adds the widget using the
* `reference_id` the API returns. Returns null unless the block name is valid, so nothing unvalidated is embedded.
*/
export function buildSetupPrompt(input: SetupPromptInput): string | null {
const name = checkBlockName(input?.blockName);
if (!name.valid) return null;

return `Set up 36Blocks authentication for my app: create a 36Blocks block named "${name.value}" and add its login widget to this project.

Docs: ${LLMS_TXT_URL}

Do these in order:
1. Connect to the 36Blocks MCP server: ${MCP_SERVER_URL}
If you can't use MCP, use the CLI instead: ${CLI_INIT_COMMAND}
2. When it asks you to sign in, I will finish the 36Blocks sign-in and approval in my browser. Don't ask me to paste a key, token or block reference id: you get everything through the connection.
3. Inspect this project to work out the framework, the production URL of the app and the sign-in methods it needs (password, Google, Apple, OTP). Ask me only if you can't infer it.
4. Create the block with the Create Login Block (Simple) tool (create_login_block): name "${name.value}", the redirect URL and the login methods. It returns the block's reference_id.
5. Read how to wire it in with Get Block Integration Details (get_block_integration), then add the widget and the redirect route to my app by following the docs. Use the block's reference_id from the API response.
6. Tell me what you changed.

Careful:
- ${REDIRECT_RULE}
- If a create call fails or times out, list my blocks (list_blocks) before retrying so you don't create a duplicate.
- Don't create a subscription block.
- Block responses can contain provider credentials: treat them as secret and never print or commit them.
- ${AUTH_KEY_RULE}`;
}

export interface ResolvedPrompt {
kind: AiPromptKind;
prompt: string;
}

/**
* Picks the prompt for the dialog: a specific block gets the block prompt, everything else (including an unusable block
* context) gets the general prompt. No prompt contains a credential.
*/
export function resolvePrompt(state: { block: BlockPromptContext | null }): ResolvedPrompt {
const blockPrompt = state.block ? buildBlockIntegrationPrompt(state.block) : null;
if (blockPrompt) return { kind: 'block', prompt: blockPrompt };
return { kind: 'general', prompt: buildGeneralIntegrationPrompt() };
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
<p class="ai-explainer">{{ explanation() }}</p>

<label class="ai-label" for="ai-prompt-field">Prompt</label>
<textarea
#promptField
id="ai-prompt-field"
class="ai-prompt"
readonly
[attr.rows]="promptRows()"
[class.ai-prompt-tall]="kind() === 'setup'"
spellcheck="false"
[value]="prompt()"
></textarea>
<div class="ai-copy-row">
<button
type="button"
mat-flat-button
class="ai-copy-button"
[class.ai-copy-failed]="stateOf('prompt') === 'failed'"
(click)="copyPrompt()"
>
<mat-icon aria-hidden="true">{{
stateOf('prompt') === 'copied' ? 'check' : stateOf('prompt') === 'failed' ? 'error_outline' : 'content_copy'
}}</mat-icon>
{{ stateOf('prompt') === 'copied' ? 'Copied' : stateOf('prompt') === 'failed' ? 'Copy failed' : 'Copy prompt' }}
</button>
<span class="ai-copy-status" role="status" aria-live="polite">
@if (stateOf('prompt') === 'copied') {
Prompt copied to your clipboard.
} @else if (stateOf('prompt') === 'failed') {
Couldn’t copy automatically. The prompt is selected, so copy it with your keyboard.
}
</span>
</div>

<h3 class="ai-subheading">{{ tabsHeading() }}</h3>
<p class="ai-note ai-signin-note">
The first time your tool connects, it opens a 36Blocks page in your browser. Sign in if asked and approve access for
the workspace shown there. You never paste a key or token.
</p>
<mat-tab-group class="ai-tabs" animationDuration="0ms" mat-stretch-tabs="false" aria-label="AI tool">
<mat-tab label="Claude Code">
<div class="ai-tab-body">
<p>Run this in your terminal to add the 36Blocks MCP server:</p>
<div class="ai-snippet">
<pre tabindex="0" aria-label="Claude Code command">{{ claudeCodeCommand }}</pre>
<button type="button" mat-stroked-button (click)="copySnippet('claude', claudeCodeCommand)">
{{
stateOf('claude') === 'copied'
? 'Copied'
: stateOf('claude') === 'failed'
? 'Copy failed'
: 'Copy'
}}
</button>
</div>
</div>
</mat-tab>
<mat-tab label="Cursor">
<div class="ai-tab-body">
<p>
Add this to <code>.cursor/mcp.json</code> in your project, or <code>~/.cursor/mcp.json</code> for all
projects:
</p>
<div class="ai-snippet">
<pre tabindex="0" aria-label="Cursor mcp.json entry">{{ cursorConfig }}</pre>
<button type="button" mat-stroked-button (click)="copySnippet('cursor', cursorConfig)">
{{
stateOf('cursor') === 'copied'
? 'Copied'
: stateOf('cursor') === 'failed'
? 'Copy failed'
: 'Copy'
}}
</button>
</div>
</div>
</mat-tab>
<mat-tab label="Other">
<div class="ai-tab-body">
<p>Add this URL as an MCP server (or connector) in your AI tool:</p>
<div class="ai-snippet">
<pre tabindex="0" aria-label="MCP server URL">{{ mcpUrl }}</pre>
<button type="button" mat-stroked-button (click)="copySnippet('url', mcpUrl)">
{{ stateOf('url') === 'copied' ? 'Copied' : stateOf('url') === 'failed' ? 'Copy failed' : 'Copy' }}
</button>
</div>
<p>No MCP support? Your agent can use the CLI instead. Install the modules once with:</p>
<div class="ai-snippet">
<pre tabindex="0" aria-label="CLI install command">{{ cliInit }}</pre>
<button type="button" mat-stroked-button (click)="copySnippet('cli', cliInit)">
{{ stateOf('cli') === 'copied' ? 'Copied' : stateOf('cli') === 'failed' ? 'Copy failed' : 'Copy' }}
</button>
</div>
</div>
</mat-tab>
</mat-tab-group>
<p class="ai-note">Never paste tokens or secrets into a prompt.</p>
Loading
Loading