@harborclient/core 0.1.1

package/dist/ai/scriptAsk.js

@@ -0,0 +1,243 @@
+/**
+ * OpenAI tool definition for the script `/ask` mini-agent response.
+ */
+export const SCRIPT_ASK_TOOL = {
+    type: 'function',
+    function: {
+        name: 'answer_script',
+        description: 'Returns a short answer for an inline /ask request in a HarborClient request script editor.',
+        parameters: {
+            type: 'object',
+            properties: {
+                note: {
+                    type: 'string',
+                    description: 'Optional short explanation inserted as // comment lines. Keep to a few lines.'
+                },
+                code: {
+                    type: 'string',
+                    description: 'Optional JavaScript snippet that replaces the /ask command line in the script.'
+                }
+            },
+            additionalProperties: false
+        }
+    }
+};
+/**
+ * Builds a numbered view of script source for the mini-agent system prompt.
+ *
+ * @param code - Full script source.
+ * @returns Lines prefixed with 1-based line numbers.
+ */
+function formatNumberedScript(code) {
+    const lines = code.split('\n');
+    const width = String(Math.max(lines.length, 1)).length;
+    return lines
+        .map((line, index) => `${String(index + 1).padStart(width, ' ')}| ${line}`)
+        .join('\n');
+}
+/**
+ * Builds the system prompt for an inline script `/ask` request.
+ *
+ * @param context - Script source, slash-command line, and phase.
+ * @returns System prompt instructing the model to call answer_script.
+ */
+export function buildScriptAskSystemPrompt(context) {
+    const phaseLabel = context.phase === 'pre' ? 'pre-request' : 'post-request';
+    return `You are an assistant embedded in HarborClient, a desktop HTTP API client.
+
+The user is editing a ${phaseLabel} request script and typed /ask on line ${context.line}. Answer very briefly about that line or the next line of code when relevant.
+
+Rules:
+1. Always respond by calling the answer_script tool exactly once.
+2. Keep answers short: at most a few comment lines or a small code snippet.
+3. Use note for brief explanations (inserted as // comments). Use code when the user needs executable JavaScript; it replaces the /ask line.
+4. Prefer code over note when the user asks for a snippet or example.
+5. Use HarborClient hc API in scripts, never Postman pm syntax.
+6. Do not mention tools, prompts, or that you are an AI.
+7. The /ask line will be replaced entirely. Do not repeat or include code from other lines in note or code.
+8. When using code, output only the new JavaScript that replaces the /ask line — never a // comment in the code field.
+9. When using note, keep it to a short explanation only; it becomes // comment lines.
+
+Script with line numbers:
+${formatNumberedScript(context.code)}`;
+}
+/**
+ * Parses tool arguments JSON from an answer_script call.
+ *
+ * @param raw - Raw JSON arguments string from the model.
+ * @returns Parsed note and/or code fields.
+ */
+function parseAnswerScriptArgs(raw) {
+    if (!raw.trim()) {
+        return {};
+    }
+    const parsed = JSON.parse(raw);
+    const answer = {};
+    if (typeof parsed.note === 'string' && parsed.note.trim()) {
+        answer.note = parsed.note.trim();
+    }
+    if (typeof parsed.code === 'string' && parsed.code.trim()) {
+        answer.code = parsed.code.trim();
+    }
+    return answer;
+}
+/**
+ * Reads an answer_script tool call from a chat step result.
+ *
+ * @param result - One LLM completion step result.
+ * @returns Parsed answer, or null when no usable response is present.
+ */
+export function parseScriptAskResult(result) {
+    const toolCall = result.toolCalls?.find((call) => call.name === 'answer_script');
+    if (toolCall) {
+        try {
+            const answer = parseAnswerScriptArgs(toolCall.arguments);
+            if (answer.note || answer.code) {
+                return answer;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const content = result.content?.trim();
+    if (content) {
+        return { note: content };
+    }
+    return null;
+}
+/**
+ * Renders a short note as one or more // comment lines.
+ *
+ * @param note - Plain-text explanation from the model.
+ * @returns Comment block suitable for insertion into a script.
+ */
+export function renderScriptAskNote(note) {
+    return note
+        .split('\n')
+        .map((line) => (line.trim() ? `// ${line.trim()}` : '//'))
+        .join('\n');
+}
+/**
+ * Suffix appended to an inline `/ask` line while the model is thinking.
+ */
+export const SCRIPT_ASK_THINKING_SUFFIX = ' Thinking...';
+/** Matches a full script line containing a slash `/ask` command. */
+const SCRIPT_ASK_LINE_PATTERN = /^(\s*)\/ask(?:[ \t]+(.*))?$/;
+/**
+ * Returns whether a script line contains a slash `/ask` command.
+ *
+ * @param line - Single line of script source (without trailing newline).
+ */
+export function isScriptAskLine(line) {
+    return SCRIPT_ASK_LINE_PATTERN.test(line);
+}
+/**
+ * Removes the inline thinking suffix from a script line when present.
+ *
+ * @param line - Single line of script source.
+ * @returns Line without {@link SCRIPT_ASK_THINKING_SUFFIX}.
+ */
+export function stripScriptAskThinking(line) {
+    if (line.endsWith(SCRIPT_ASK_THINKING_SUFFIX)) {
+        return line.slice(0, -SCRIPT_ASK_THINKING_SUFFIX.length);
+    }
+    return line;
+}
+/**
+ * Appends the thinking suffix to the target `/ask` line only.
+ *
+ * @param code - Current script source.
+ * @param lineNumber - 1-based line number of the `/ask` command.
+ * @returns Updated script source.
+ */
+export function appendScriptAskThinking(code, lineNumber) {
+    const lines = code.split('\n');
+    const index = lineNumber - 1;
+    if (index < 0 || index >= lines.length) {
+        return code;
+    }
+    lines[index] = `${lines[index]}${SCRIPT_ASK_THINKING_SUFFIX}`;
+    return lines.join('\n');
+}
+/**
+ * Applies an answer by replacing the entire `/ask` line identified by line number.
+ *
+ * @param code - Current script source.
+ * @param lineNumber - 1-based line number of the `/ask` command.
+ * @param answer - Parsed note and/or code from the model.
+ * @param options - Optional apply behavior overrides.
+ * @returns Updated script source; unchanged when the target line is not `/ask` unless
+ *   {@link ApplyScriptAskAtLineOptions.replaceMissingAskLine} is set.
+ */
+export function applyScriptAskAtLine(code, lineNumber, answer, options) {
+    const lines = code.split('\n');
+    const index = lineNumber - 1;
+    if (index < 0 || index >= lines.length) {
+        return code;
+    }
+    const line = stripScriptAskThinking(lines[index]);
+    if (!isScriptAskLine(line) && !options?.replaceMissingAskLine) {
+        return code;
+    }
+    const replacement = answer.code != null && answer.code.length > 0
+        ? answer.code
+        : answer.note
+            ? renderScriptAskNote(answer.note)
+            : '';
+    lines[index] = replacement;
+    return lines.join('\n');
+}
+/**
+ * Removes the entire `/ask` line when the modal closes without an answer.
+ *
+ * @param code - Current script source.
+ * @param lineNumber - 1-based line number of the `/ask` command.
+ * @returns Script source with the command line removed.
+ */
+export function removeScriptAskLine(code, lineNumber) {
+    const lines = code.split('\n');
+    const index = lineNumber - 1;
+    if (index < 0 || index >= lines.length) {
+        return code;
+    }
+    const line = stripScriptAskThinking(lines[index]);
+    if (!isScriptAskLine(line)) {
+        return code;
+    }
+    lines.splice(index, 1);
+    return lines.join('\n');
+}
+/**
+ * Applies an answer_script result by replacing the slash command span in the script.
+ *
+ * @param code - Current script source.
+ * @param from - Start offset of the slash command span (inclusive).
+ * @param to - End offset of the slash command span (exclusive).
+ * @param answer - Parsed note and/or code from the model.
+ * @returns Updated script source.
+ */
+export function applyScriptAsk(code, from, to, answer) {
+    const replacement = answer.code != null && answer.code.length > 0
+        ? answer.code
+        : answer.note
+            ? renderScriptAskNote(answer.note)
+            : '';
+    return code.slice(0, from) + replacement + code.slice(to);
+}
+/**
+ * Removes the slash command span from the script when the modal closes without an answer.
+ *
+ * @param code - Current script source.
+ * @param from - Start offset of the slash command span (inclusive).
+ * @param to - End offset of the slash command span (exclusive).
+ * @returns Script source with the command removed and adjacent blank lines tidied.
+ */
+export function removeScriptAskCommand(code, from, to) {
+    let next = code.slice(0, from) + code.slice(to);
+    if (from > 0 && next[from - 1] === '\n' && (next[from] === '\n' || next.length === from)) {
+        next = next.slice(0, from - 1) + next.slice(from);
+    }
+    return next;
+}
+//# sourceMappingURL=scriptAsk.js.map

package/dist/ai/scriptAsk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptAsk.js","sourceRoot":"","sources":["../../src/ai/scriptAsk.ts"],"names":[],"mappings":"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"}

package/dist/ai/scriptReferences.d.ts

@@ -0,0 +1,377 @@
+import type { ScriptRef, Snippet } from '../types';
+/**
+ * Regex matching `@` script references in chat text:
+ * - Request scripts: `@<request-id>.<pre|post>.<script-index>`
+ * - Standalone snippets: `@snippet.<uuid>`
+ * - Footer terminals: `@term.<terminal-index>`
+ * - Collections: `@collection.<uuid>`
+ * - Folders: `@folder.<uuid>`
+ * - Saved requests: `@request.<uuid>`
+ * - Markdown documents and request comments: `@markdown.<uuid>`
+ * - Active request raw body: `@body`
+ *
+ * Request scripts, snippets, markdown, and raw body accept an optional
+ * `#<selection-start>.<selection-end>` suffix (character offsets). Terminal references use the
+ * same suffix for 1-based line numbers.
+ */
+export declare const AI_SCRIPT_REFERENCE_PATTERN: RegExp;
+/**
+ * Shared fields for every parsed `@` script reference.
+ */
+interface ParsedAiScriptReferenceBase {
+    /**
+     * Start offset of the full `@` token in the source text.
+     */
+    start: number;
+    /**
+     * End offset (exclusive) of the full `@` token in the source text.
+     */
+    end: number;
+    /**
+     * Exact matched substring, including the leading `@`.
+     */
+    text: string;
+    /**
+     * Character offsets into the referenced script source when the user selected a range.
+     */
+    selection?: {
+        /**
+         * Start offset (inclusive) in the script source.
+         */
+        start: number;
+        /**
+         * End offset (exclusive) in the script source.
+         */
+        end: number;
+    };
+}
+/**
+ * A parsed `@` reference to a request script row.
+ */
+export interface ParsedRequestScriptReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for request-script references.
+     */
+    kind: 'request-script';
+    /**
+     * Saved request id from the reference, or the literal `active`.
+     */
+    requestId: number | 'active';
+    /**
+     * Script phase: pre-request or post-request.
+     */
+    phase: 'pre' | 'post';
+    /**
+     * 1-based index of the script in the phase array.
+     */
+    scriptIndex: number;
+}
+/**
+ * A parsed `@` reference to a standalone library snippet.
+ */
+export interface ParsedSnippetReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for standalone snippet references.
+     */
+    kind: 'snippet';
+    /**
+     * UUID of the snippet in the library.
+     */
+    snippetUuid: string;
+}
+/**
+ * A parsed `@` reference to a footer terminal selection.
+ */
+export interface ParsedTerminalReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for footer terminal references.
+     */
+    kind: 'terminal';
+    /**
+     * 1-based index of the terminal tab in the footer switcher.
+     */
+    terminalIndex: number;
+}
+/**
+ * A parsed `@` reference to a collection in the sidebar.
+ */
+export interface ParsedCollectionReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for collection references.
+     */
+    kind: 'collection';
+    /**
+     * UUID of the collection.
+     */
+    collectionUuid: string;
+}
+/**
+ * A parsed `@` reference to a folder in the sidebar.
+ */
+export interface ParsedFolderReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for folder references.
+     */
+    kind: 'folder';
+    /**
+     * UUID of the folder.
+     */
+    folderUuid: string;
+}
+/**
+ * A parsed `@` reference to a saved request in the sidebar.
+ */
+export interface ParsedRequestReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for saved-request references.
+     */
+    kind: 'request';
+    /**
+     * UUID of the saved request.
+     */
+    requestUuid: string;
+}
+/**
+ * A parsed `@` reference to a collection markdown document or request comment.
+ */
+export interface ParsedMarkdownReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for markdown document and comment references.
+     */
+    kind: 'markdown';
+    /**
+     * UUID of the collection document or saved request.
+     */
+    markdownUuid: string;
+}
+/**
+ * A parsed `@` reference to the active request's raw body editor.
+ */
+export interface ParsedRequestBodyReference extends ParsedAiScriptReferenceBase {
+    /**
+     * Discriminator for raw-body selection references.
+     */
+    kind: 'body';
+}
+/**
+ * Snapshot of terminal output captured when the user copies a selection to chat.
+ */
+export interface TerminalSelectionSnapshot {
+    /**
+     * Display label of the terminal tab at capture time.
+     */
+    terminalLabel: string;
+    /**
+     * 1-based start line of the selection in the xterm buffer.
+     */
+    startLine: number;
+    /**
+     * 1-based end line of the selection in the xterm buffer.
+     */
+    endLine: number;
+    /**
+     * Plain-text content of the user's selection.
+     */
+    selectedText: string;
+    /**
+     * Surrounding terminal lines included for agent context.
+     */
+    contextText: string;
+}
+/**
+ * Snapshot of markdown text captured when the user copies a selection to chat.
+ */
+export interface MarkdownSelectionSnapshot {
+    /**
+     * Display label at capture time (for example "Document: README.md").
+     */
+    label: string;
+    /**
+     * Plain-text content of the user's selection.
+     */
+    selectedText: string;
+    /**
+     * Best-effort start offset in the markdown source.
+     */
+    startOffset: number;
+    /**
+     * Best-effort end offset in the markdown source.
+     */
+    endOffset: number;
+    /**
+     * 1-based start line of the selection in the markdown source.
+     */
+    startLine: number;
+    /**
+     * 1-based end line of the selection in the markdown source.
+     */
+    endLine: number;
+}
+/**
+ * Snapshot of raw request body text captured when the user copies a selection to chat.
+ */
+export interface RequestBodySelectionSnapshot {
+    /**
+     * Display label at capture time (for example "Raw multipart body").
+     */
+    label: string;
+    /**
+     * Plain-text content of the user's selection.
+     */
+    selectedText: string;
+    /**
+     * Start offset in the raw body editor text.
+     */
+    startOffset: number;
+    /**
+     * End offset in the raw body editor text.
+     */
+    endOffset: number;
+    /**
+     * 1-based start line of the selection in the raw body text.
+     */
+    startLine: number;
+    /**
+     * 1-based end line of the selection in the raw body text.
+     */
+    endLine: number;
+}
+/**
+ * A parsed `@` script reference with character offsets in the source text.
+ */
+export type ParsedAiScriptReference = ParsedRequestScriptReference | ParsedSnippetReference | ParsedTerminalReference | ParsedCollectionReference | ParsedFolderReference | ParsedRequestReference | ParsedMarkdownReference | ParsedRequestBodyReference;
+/**
+ * Active request tab state used to decide whether an `@` reference is highlightable.
+ */
+export interface AiScriptReferenceValidationContext {
+    /**
+     * Whether the active tab hosts a request editor draft.
+     */
+    hasActiveRequestTab: boolean;
+    /**
+     * Saved request id on the active draft, when the tab is saved.
+     */
+    activeRequestId?: number;
+    /**
+     * Number of pre-request scripts on the active draft.
+     */
+    preScriptCount: number;
+    /**
+     * Number of post-request scripts on the active draft.
+     */
+    postScriptCount: number;
+    /**
+     * Pre-request script rows on the active draft, when available for name resolution.
+     */
+    preScripts?: ScriptRef[];
+    /**
+     * Post-request script rows on the active draft, when available for name resolution.
+     */
+    postScripts?: ScriptRef[];
+    /**
+     * Snippet library used to resolve snippet-linked script names.
+     */
+    snippets?: Snippet[];
+    /**
+     * Terminal selection snapshots keyed by the full `@term` reference token.
+     */
+    terminalSelections?: Record<string, TerminalSelectionSnapshot>;
+    /**
+     * Markdown selection snapshots keyed by the full `@markdown` reference token.
+     */
+    markdownSelections?: Record<string, MarkdownSelectionSnapshot>;
+    /**
+     * Raw-body selection snapshots keyed by the full `@body` reference token.
+     */
+    requestBodySelections?: Record<string, RequestBodySelectionSnapshot>;
+    /**
+     * Collection display names keyed by uuid for `@collection` badge resolution.
+     */
+    collectionNamesByUuid?: Record<string, string>;
+    /**
+     * Folder display names keyed by uuid for `@folder` badge resolution.
+     */
+    folderNamesByUuid?: Record<string, string>;
+    /**
+     * Saved request display names keyed by uuid for `@request` badge resolution.
+     */
+    requestNamesByUuid?: Record<string, string>;
+}
+/**
+ * One render segment for the chat composer backdrop.
+ */
+export interface ChatComposerTextToken {
+    /**
+     * Substring from the composer draft.
+     */
+    text: string;
+    /**
+     * When true, the segment is a valid `@` script reference and should be highlighted.
+     */
+    highlight: boolean;
+    /**
+     * Parsed reference metadata when {@link highlight} is true.
+     */
+    reference?: ParsedAiScriptReference;
+}
+/**
+ * Parses one regex match into a structured script reference.
+ *
+ * @param match - RegExp match for {@link AI_SCRIPT_REFERENCE_PATTERN}.
+ * @param start - Document start offset of the match.
+ */
+export declare function parseAiScriptReferenceMatch(match: RegExpMatchArray, start: number): ParsedAiScriptReference | null;
+/**
+ * Finds syntactically valid `@` script reference candidates in plain text.
+ *
+ * @param text - Composer draft that may contain `@` references.
+ */
+export declare function findAiScriptReferenceCandidates(text: string): ParsedAiScriptReference[];
+/**
+ * Removes valid `@` script reference tokens from plain text.
+ *
+ * @param text - Composer or title prompt text that may contain `@` references.
+ * @returns Text with script references removed and whitespace collapsed.
+ */
+export declare function stripAiScriptReferences(text: string): string;
+/**
+ * Returns whether a parsed `@` reference resolves against the active request tab or snippet library.
+ *
+ * Mirrors `update_request_script` validation in the AI tool executor for request-script kind.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script counts, request id, and snippet library.
+ */
+export declare function isValidAiScriptReference(reference: ParsedAiScriptReference, context: AiScriptReferenceValidationContext): boolean;
+/**
+ * Resolves the display name for a valid `@` script reference.
+ *
+ * @param reference - Parsed `@` script reference.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Script or snippet name when resolvable, otherwise null.
+ */
+export declare function resolveAiScriptReferenceName(reference: ParsedAiScriptReference, context: AiScriptReferenceValidationContext): string | null;
+export declare function resolveAiScriptReferenceLabel(reference: ParsedAiScriptReference, context: AiScriptReferenceValidationContext): string | null;
+/**
+ * Builds an ephemeral system message that expands valid `@` script references in the user message.
+ *
+ * References with a `#start.end` suffix include the selected substring; whole-script references
+ * include the full source so the model can answer questions without relying on tool calls alone.
+ *
+ * The returned text is injected into the LLM step messages only; it is not persisted in chat
+ * history so the composer can keep rendering compact badges.
+ *
+ * @param text - User message that may contain `@` script references.
+ * @param context - Active tab script rows and snippet library.
+ * @returns Formatted context block, or null when no valid references are present.
+ */
+export declare function buildAiScriptSelectionContextMessage(text: string, context: AiScriptReferenceValidationContext): string | null;
+/**
+ * Splits composer text into plain and highlightable `@` script reference segments.
+ *
+ * @param text - Composer draft.
+ * @param context - Active tab state for semantic validation.
+ */
+export declare function tokenizeChatComposerText(text: string, context: AiScriptReferenceValidationContext): ChatComposerTextToken[];
+export {};
+//# sourceMappingURL=scriptReferences.d.ts.map

package/dist/ai/scriptReferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptReferences.d.ts","sourceRoot":"","sources":["../../src/ai/scriptReferences.ts"],"names":[],"mappings":"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"}