@docyrus/docyrus 0.0.25 → 0.0.27

package/resources/pi-agent/shared/askUserProtocol.ts

@@ -0,0 +1,248 @@
+export const ASK_USER_TAG = "ask_user";
+export const ASK_USER_OPEN = `<${ASK_USER_TAG}>`;
+export const ASK_USER_CLOSE = `</${ASK_USER_TAG}>`;
+export const ASK_USER_RESPONSE_TAG = "ask_user_response";
+export const ASK_USER_RESPONSE_OPEN = `<${ASK_USER_RESPONSE_TAG}>`;
+export const ASK_USER_RESPONSE_CLOSE = `</${ASK_USER_RESPONSE_TAG}>`;
+
+export type IAskUserQuestionType = "text" | "textarea" | "boolean" | "singleSelect" | "multiSelect";
+export type IAskUserAnswerValue = string | boolean | string[];
+
+export interface IAskUserOption {
+	label: string;
+	value: string;
+}
+
+export interface IAskUserQuestion {
+	id: string;
+	label: string;
+	description?: string;
+	type: IAskUserQuestionType;
+	required?: boolean;
+	options?: IAskUserOption[];
+	placeholder?: string;
+	defaultValue?: IAskUserAnswerValue;
+}
+
+export interface IAskUserRequest {
+	title: string;
+	message: string;
+	questions: IAskUserQuestion[];
+}
+
+export interface IAskUserResponse {
+	action: "submit" | "cancel" | "decline";
+	answers: Record<string, IAskUserAnswerValue>;
+}
+
+function hashString(value: string): string {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash) + value.charCodeAt(index);
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function normalizeTrimmedString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function normalizeQuestionType(value: unknown): IAskUserQuestionType | undefined {
+  return value === "text" ||
+		value === "textarea" ||
+		value === "boolean" ||
+		value === "singleSelect" ||
+		value === "multiSelect"
+    ? value
+    : undefined;
+}
+
+function normalizeDefaultValue(value: unknown): IAskUserAnswerValue | undefined {
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return [...value];
+  }
+  return undefined;
+}
+
+function normalizeOptions(value: unknown): IAskUserOption[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const options: IAskUserOption[] = [];
+  for (const item of value) {
+    if (!isRecord(item) || !isNonEmptyString(item.label) || !isNonEmptyString(item.value)) {
+      return undefined;
+    }
+    options.push({
+      label: item.label.trim(),
+      value: item.value.trim(),
+    });
+  }
+
+  return options;
+}
+
+export function normalizeAskUserQuestion(value: unknown): IAskUserQuestion | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const id = normalizeTrimmedString(value.id);
+  const label = normalizeTrimmedString(value.label);
+  const type = normalizeQuestionType(value.type);
+  if (!id || !label || !type) {
+    return undefined;
+  }
+
+  const question: IAskUserQuestion = {
+    id,
+    label,
+    type,
+  };
+
+  const description = normalizeTrimmedString(value.description);
+  if (description) {
+    question.description = description;
+  }
+
+  if (typeof value.required === "boolean") {
+    question.required = value.required;
+  }
+
+  const options = normalizeOptions(value.options);
+  if (type === "singleSelect" || type === "multiSelect") {
+    if (!options || options.length === 0) {
+      return undefined;
+    }
+    question.options = options;
+  }
+
+  const placeholder = normalizeTrimmedString(value.placeholder);
+  if (placeholder) {
+    question.placeholder = placeholder;
+  }
+
+  const defaultValue = normalizeDefaultValue(value.defaultValue);
+  if (defaultValue !== undefined) {
+    question.defaultValue = defaultValue;
+  }
+
+  return question;
+}
+
+export function normalizeAskUserRequest(value: unknown): IAskUserRequest | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const title = normalizeTrimmedString(value.title);
+  const message = normalizeTrimmedString(value.message);
+  if (!title || !message || !Array.isArray(value.questions) || value.questions.length === 0) {
+    return undefined;
+  }
+
+  const questions: IAskUserQuestion[] = [];
+  for (const question of value.questions) {
+    const normalized = normalizeAskUserQuestion(question);
+    if (!normalized) {
+      return undefined;
+    }
+    questions.push(normalized);
+  }
+
+  return {
+    title,
+    message,
+    questions,
+  };
+}
+
+export function normalizeAskUserResponse(value: unknown): IAskUserResponse | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const action = value.action;
+  if (action !== "submit" && action !== "cancel" && action !== "decline") {
+    return undefined;
+  }
+
+  const answersRecord = isRecord(value.answers) ? value.answers : {};
+  const answers: Record<string, IAskUserAnswerValue> = {};
+  for (const [key, answerValue] of Object.entries(answersRecord)) {
+    const normalized = normalizeDefaultValue(answerValue);
+    if (normalized !== undefined) {
+      answers[key] = normalized;
+    }
+  }
+
+  return {
+    action,
+    answers,
+  };
+}
+
+export function buildAskUserProtocolInstructions(): string {
+  return [
+    "When clarification is required, do not ask free-form prose questions.",
+    `Instead, output only a single ${ASK_USER_OPEN}...${ASK_USER_CLOSE} block and nothing else in the assistant message.`,
+    "Inside that block, emit strict JSON with this shape:",
+    '{"title":"...","message":"...","questions":[{"id":"...","label":"...","description":"...","type":"text|textarea|boolean|singleSelect|multiSelect","required":true,"options":[{"label":"...","value":"..."}],"placeholder":"...","defaultValue":"..."}]}',
+    "Use batch questions when possible, keep ids stable, and limit the batch to the minimum needed to continue planning.",
+  ].join("\n");
+}
+
+export function serializeAskUserRequest(request: IAskUserRequest): string {
+  return `${ASK_USER_OPEN}\n${JSON.stringify(request, null, 2)}\n${ASK_USER_CLOSE}`;
+}
+
+export function createAskUserToolCallId(request: IAskUserRequest): string {
+  return `ask_user_${hashString(JSON.stringify(request))}`;
+}
+
+export function parseAskUserRequestFromText(text: string): IAskUserRequest | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(ASK_USER_OPEN) || !trimmed.endsWith(ASK_USER_CLOSE)) {
+    return undefined;
+  }
+
+  const body = trimmed.slice(ASK_USER_OPEN.length, trimmed.length - ASK_USER_CLOSE.length).trim();
+  if (!body) {
+    return undefined;
+  }
+
+  try {
+    return normalizeAskUserRequest(JSON.parse(body));
+  } catch {
+    return undefined;
+  }
+}
+
+export function formatAskUserResponsePrompt(response: IAskUserResponse): string {
+  return [
+    "The user submitted structured clarification answers.",
+    "",
+    `${ASK_USER_RESPONSE_OPEN}`,
+    JSON.stringify(response, null, 2),
+    `${ASK_USER_RESPONSE_CLOSE}`,
+    "",
+    "Continue the planning workflow using these answers.",
+  ].join("\n");
+}
+
+export function parseAskUserResponseFromToolOutput(output: unknown): IAskUserResponse | undefined {
+  return normalizeAskUserResponse(output);
+}

package/resources/pi-agent/skills/docyrus-platform/SKILL.md

@@ -24,7 +24,7 @@ For detailed specifications of each building block, see [references/core-buildin
 
 ### Querying & Data Operations
 
-Unified query engine with column selection, 50+ filter operators, aggregations, formulas, pivots, child queries, and full-text search. Full CRUD with bulk operations.
+Unified query engine with column selection, 50+ filter operators, aggregations, formulas, pivots, child queries, and full-text search. Full CRUD with bulk operations, record comments, and file attachments.
 
 See [references/querying-and-data-operations.md](references/querying-and-data-operations.md).
 

package/resources/pi-agent/skills/docyrus-platform/references/developer-tools.md

@@ -14,7 +14,7 @@
 ## CLI
 
 - Full-featured CLI (`@docyrus/docyrus`) for terminal and AI agent use
-- Commands: environment management, authentication, data operations, schema management (studio), app management, API discovery, AI chat, and direct API requests
+- Commands: environment management, authentication, data operations, record comments, record file attachments, schema management (studio), app management, API discovery, AI chat, and direct API requests
 - Multi-account, multi-tenant session management
 - OpenAPI discovery with caching and fallback generation
 - Interactive TUI mode

package/resources/pi-agent/skills/docyrus-platform/references/docyrus-cli-usage.md

@@ -251,6 +251,52 @@ Delete a data source item.
 | `dataSourceSlug` | string | yes | Data source slug |
 | `recordId` | string | yes | Record ID |
 
+### `docyrus ds comments create <appSlug> <dataSourceSlug> <recordId>`
+
+Create a record-scoped comment.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+| `recordId` | string | yes | Record ID |
+
+| Option | Type | Description |
+|---|---|---|
+| `--message` | string | Comment message |
+| `--data` | string | Full JSON payload for the comment DTO |
+| `--fromFile` | string | Path to a JSON payload file |
+| `--parentId` | string | Parent comment ID |
+| `--assignedTo` | string | Assigned user ID |
+| `--attachments` | string | JSON attachments payload |
+| `--level` | number | Comment level |
+| `--status` | number | Comment status |
+| `--done` | boolean | Mark comment as done |
+
+**Notes:**
+- Use either `--message` or `--data` / `--fromFile`
+- `--data` and `--fromFile` cannot be mixed with field-specific flags
+
+### `docyrus ds files upload <appSlug> <dataSourceSlug> <recordId>`
+
+Upload a record-scoped file attachment.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+| `recordId` | string | yes | Record ID |
+
+| Option | Type | Description |
+|---|---|---|
+| `--file` | string | Path to the local file to upload |
+| `--contentType` | string | Override the inferred MIME type |
+| `--publicFile` | boolean | Store the file in the public tenant bucket |
+
+**Notes:**
+- Uploads use `multipart/form-data`
+- Content type is inferred from the file extension when omitted
+
 ---
 
 ## discover — OpenAPI Discovery

package/resources/pi-agent/skills/docyrus-platform/references/querying-and-data-operations.md

@@ -6,6 +6,13 @@
 - Bulk create, bulk update, bulk delete (batched for performance)
 - Insert/update/delete with custom return value selection
 
+## Record Comments & Files
+
+- Record-scoped comments with create, list, fetch by ID, update, and delete operations
+- Comment payloads can include threading (`parentId`), assignee targeting (`assignedTo`), attachments metadata, level, status, and done state
+- Record-scoped file attachments with upload, list, fetch by ID, insert-without-upload, copy/move, and delete operations
+- File uploads support multipart form data, public/private storage selection, and record association
+
 ## Query Engine
 
 Every list/get call accepts a structured query payload: