@dinoxx/dinox-cli 1.0.18 → 1.0.20

package/dist/skills/check.js

@@ -0,0 +1,254 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findCommandSchema, listCommandSchemas } from '../commands/schema/spec.js';
+const EXEMPT_SHARED_REFERENCE = new Set(['dino-dinox', 'dino-shared']);
+const SHARED_REFERENCE_PATTERN = /\.\.\/dino-shared\/SKILL\.md/;
+const BINS_PATTERN = /^metadata:\s*[\s\S]*?^  requires:\s*[\s\S]*?^    bins:\s*\[(.*?)\]\s*$/m;
+const CLI_HELP_PATTERN = /^metadata:\s*[\s\S]*?^  cliHelp:\s*.+$/m;
+const commandSchemas = listCommandSchemas();
+const commandSchemaPrefixes = commandSchemas
+    .map((schema) => ({
+    schema,
+    tokens: schema.command.split(/\s+/g),
+}))
+    .sort((left, right) => right.tokens.length - left.tokens.length);
+function parseFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        frontmatter: match[1] ?? '',
+        body: match[2] ?? '',
+    };
+}
+function extractRelativeMarkdownLinks(body) {
+    const links = new Set();
+    const pattern = /\[[^\]]+\]\(([^)]+\.md)\)/g;
+    let match = null;
+    while ((match = pattern.exec(body)) !== null) {
+        const target = match[1]?.trim();
+        if (!target || target.startsWith('http://') || target.startsWith('https://')) {
+            continue;
+        }
+        links.add(target);
+    }
+    return [...links];
+}
+function walkMarkdownFiles(skillDir) {
+    const files = [];
+    for (const entry of fs.readdirSync(skillDir, { withFileTypes: true })) {
+        const fullPath = path.join(skillDir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkMarkdownFiles(fullPath));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(fullPath);
+        }
+    }
+    return files.sort();
+}
+function extractDinoCommands(markdown) {
+    const commands = [];
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    let inCodeFence = false;
+    let currentCommand = '';
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('```')) {
+            inCodeFence = !inCodeFence;
+            currentCommand = '';
+            continue;
+        }
+        if (!inCodeFence || trimmed === '' || trimmed.startsWith('#')) {
+            continue;
+        }
+        if (!currentCommand && !trimmed.startsWith('dino ')) {
+            continue;
+        }
+        const continued = trimmed.endsWith('\\');
+        const segment = continued ? trimmed.slice(0, -1).trimEnd() : trimmed;
+        currentCommand = currentCommand ? `${currentCommand} ${segment}` : segment;
+        if (!continued) {
+            commands.push(currentCommand);
+            currentCommand = '';
+        }
+    }
+    return commands;
+}
+function tokenizeShellCommand(command) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (current) {
+                tokens.push(current);
+                current = '';
+            }
+            continue;
+        }
+        if (char === '\\' && index + 1 < command.length) {
+            current += command[index + 1];
+            index += 1;
+            continue;
+        }
+        current += char;
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+function extractOptionNames(tokens) {
+    return tokens
+        .filter((token) => token.startsWith('--'))
+        .map((token) => token.split('=', 1)[0] ?? token);
+}
+function normalizeOptionName(option) {
+    return option.trim().split(/\s+/g)[0] ?? option.trim();
+}
+function isPlaceholderToken(token) {
+    return /^[$<[].*/.test(token);
+}
+function validateDinoCommandExample(command) {
+    const tokens = tokenizeShellCommand(command);
+    if (tokens[0] !== 'dino') {
+        return [];
+    }
+    const match = commandSchemaPrefixes.find(({ tokens: prefix }) => prefix.every((token, index) => tokens[index] === token));
+    if (!match) {
+        return [`Unknown dino command example: ${command}`];
+    }
+    const allowedOptions = new Set([...(match.schema.options ?? []), ...match.schema.globalOptions.map((name) => ({ name }))]
+        .map((option) => normalizeOptionName(option.name)));
+    const optionIssues = extractOptionNames(tokens.slice(match.tokens.length))
+        .filter((option) => !allowedOptions.has(option))
+        .map((option) => `Unknown option ${option} in command example: ${command}`);
+    if (match.schema.path === 'schema') {
+        const schemaPathToken = tokens[match.tokens.length];
+        if (schemaPathToken && !schemaPathToken.startsWith('--') && !isPlaceholderToken(schemaPathToken)) {
+            if (!findCommandSchema(schemaPathToken)) {
+                optionIssues.push(`Unknown schema path ${schemaPathToken} in command example: ${command}`);
+            }
+        }
+    }
+    return optionIssues;
+}
+function checkMarkdownDocument(skill, content, relativePath, skillDir) {
+    const issues = [];
+    for (const relativeTarget of extractRelativeMarkdownLinks(content)) {
+        const resolved = path.resolve(path.dirname(path.join(skillDir, relativePath)), relativeTarget);
+        if (!fs.existsSync(resolved)) {
+            issues.push({ skill, message: `${relativePath}: referenced markdown file does not exist: ${relativeTarget}` });
+        }
+    }
+    for (const command of extractDinoCommands(content)) {
+        for (const issue of validateDinoCommandExample(command)) {
+            issues.push({ skill, message: `${relativePath}: ${issue}` });
+        }
+    }
+    return issues;
+}
+export function checkSkillContent(skill, content, skillDir) {
+    const issues = [];
+    const parsed = parseFrontmatter(content);
+    if (!parsed) {
+        return [{ skill, message: 'SKILL.md must start with valid YAML frontmatter.' }];
+    }
+    const { frontmatter, body } = parsed;
+    const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+    if (!nameMatch) {
+        issues.push({ skill, message: "Frontmatter is missing 'name'." });
+    }
+    else if (nameMatch[1]?.trim() !== skill) {
+        issues.push({ skill, message: `Frontmatter name must match directory name (${skill}).` });
+    }
+    if (!/^description:\s*/m.test(frontmatter)) {
+        issues.push({ skill, message: "Frontmatter is missing 'description'." });
+    }
+    if (!/^metadata:\s*$/m.test(frontmatter)) {
+        issues.push({ skill, message: "Frontmatter is missing 'metadata'." });
+    }
+    const binsMatch = frontmatter.match(BINS_PATTERN);
+    if (!binsMatch) {
+        issues.push({ skill, message: "Frontmatter must include metadata.requires.bins." });
+    }
+    else {
+        const bins = binsMatch[1]?.split(',').map((value) => value.replace(/["'\s]/g, '')).filter(Boolean) ?? [];
+        if (!bins.includes('dino')) {
+            issues.push({ skill, message: "metadata.requires.bins must include 'dino'." });
+        }
+    }
+    if (!CLI_HELP_PATTERN.test(frontmatter)) {
+        issues.push({ skill, message: "Frontmatter should include 'metadata.cliHelp'." });
+    }
+    if (skill === 'dino-shared' && !/^user-invocable:\s*false\s*$/m.test(frontmatter)) {
+        issues.push({ skill, message: "dino-shared must declare 'user-invocable: false'." });
+    }
+    if (skill === 'dino-dinox' && !/^user-invocable:\s*false\s*$/m.test(frontmatter)) {
+        issues.push({ skill, message: "dino-dinox must declare 'user-invocable: false'." });
+    }
+    if (!EXEMPT_SHARED_REFERENCE.has(skill) && !/^argument-hint:\s*/m.test(frontmatter)) {
+        issues.push({ skill, message: "User-invocable skills should declare 'argument-hint'." });
+    }
+    if (!EXEMPT_SHARED_REFERENCE.has(skill) && !/^allowed-tools:\s*$/m.test(frontmatter)) {
+        issues.push({ skill, message: "User-invocable skills should declare 'allowed-tools'." });
+    }
+    if (!EXEMPT_SHARED_REFERENCE.has(skill) && !SHARED_REFERENCE_PATTERN.test(body)) {
+        issues.push({ skill, message: 'User-invocable skills must tell the agent to read ../dino-shared/SKILL.md first.' });
+    }
+    if (!EXEMPT_SHARED_REFERENCE.has(skill) && !/^## Safety & Boundaries/m.test(body)) {
+        issues.push({ skill, message: "User-invocable skills should include a '## Safety & Boundaries' section." });
+    }
+    if (!EXEMPT_SHARED_REFERENCE.has(skill) && body.includes('dino ') && !body.includes('--format json')) {
+        issues.push({ skill, message: 'Skills that invoke dino commands must recommend --format json.' });
+    }
+    if (skill !== 'dino-dinox' && body.includes('--json')) {
+        issues.push({ skill, message: 'Skills should not recommend the legacy --json flag.' });
+    }
+    if (skillDir) {
+        issues.push(...checkMarkdownDocument(skill, body, 'SKILL.md', skillDir));
+    }
+    return issues;
+}
+export function checkSkillsDirectory(skillsDir) {
+    const issues = [];
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const skill of entries) {
+        const skillFile = path.join(skillsDir, skill, 'SKILL.md');
+        if (!fs.existsSync(skillFile)) {
+            issues.push({ skill, message: 'Missing SKILL.md.' });
+            continue;
+        }
+        const content = fs.readFileSync(skillFile, 'utf8');
+        issues.push(...checkSkillContent(skill, content, path.dirname(skillFile)));
+        const markdownFiles = walkMarkdownFiles(path.dirname(skillFile))
+            .filter((file) => file !== skillFile);
+        for (const markdownFile of markdownFiles) {
+            const relativePath = path.relative(path.dirname(skillFile), markdownFile);
+            const markdownContent = fs.readFileSync(markdownFile, 'utf8');
+            issues.push(...checkMarkdownDocument(skill, markdownContent, relativePath, path.dirname(skillFile)));
+        }
+    }
+    return issues;
+}

package/dist/utils/bidlinkCanonicalization.d.ts

@@ -0,0 +1,2 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+export declare function canonicalizeBidlinksInMarkdown(db: AbstractPowerSyncDatabase, markdown: string, userId: string): Promise<string>;

package/dist/utils/bidlinkCanonicalization.js

@@ -0,0 +1,161 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+function parseBidlinkRaw(raw) {
+    const match = raw.match(/^\[\[((?:\\.|[^\]\n])+?)\]\]$/);
+    if (!match) {
+        return null;
+    }
+    const rawValue = match[1].trim();
+    if (!rawValue) {
+        return null;
+    }
+    let separatorIndex = -1;
+    for (let index = rawValue.length - 1; index >= 0; index -= 1) {
+        if (rawValue[index] === '|' && rawValue[index - 1] !== '\\') {
+            separatorIndex = index;
+            break;
+        }
+    }
+    const unescape = (value) => value.replace(/\\([\\|\]])/g, '$1');
+    const label = unescape(separatorIndex >= 0 ? rawValue.slice(0, separatorIndex).trim() : rawValue.trim());
+    const explicitId = separatorIndex >= 0
+        ? unescape(rawValue.slice(separatorIndex + 1).trim())
+        : null;
+    if (!label) {
+        return null;
+    }
+    return {
+        explicitId: explicitId && explicitId.trim() ? explicitId : null,
+        hasExplicitId: separatorIndex >= 0 && Boolean(explicitId && explicitId.trim()),
+        label,
+    };
+}
+function escapeBidlinkValue(value) {
+    return value.replace(/([\\|\]])/g, '\\$1');
+}
+function collectBidlinkOccurrencesFromText(value, baseOffset) {
+    const occurrences = [];
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index] !== '[' || value[index + 1] !== '[') {
+            continue;
+        }
+        const slice = value.slice(index);
+        const match = slice.match(/^\[\[((?:\\.|[^\]\n])+?)\]\]/);
+        if (!match) {
+            continue;
+        }
+        const raw = match[0];
+        const parsed = parseBidlinkRaw(raw);
+        if (!parsed || parsed.hasExplicitId) {
+            index += raw.length - 1;
+            continue;
+        }
+        occurrences.push({
+            endOffset: baseOffset + index + raw.length,
+            label: parsed.label,
+            raw,
+            startOffset: baseOffset + index,
+        });
+        index += raw.length - 1;
+    }
+    return occurrences;
+}
+function collectBidlinkOccurrences(markdown) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(markdown);
+    const stack = [tree];
+    const occurrences = [];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node) {
+            continue;
+        }
+        if (node.type === 'text' && typeof node.value === 'string') {
+            const startOffset = node.position?.start?.offset;
+            const endOffset = node.position?.end?.offset;
+            if (typeof startOffset === 'number' &&
+                typeof endOffset === 'number' &&
+                endOffset >= startOffset) {
+                occurrences.push(...collectBidlinkOccurrencesFromText(node.value, startOffset));
+            }
+        }
+        const children = Array.isArray(node.children) ? node.children : [];
+        for (let index = children.length - 1; index >= 0; index -= 1) {
+            stack.push(children[index]);
+        }
+    }
+    return occurrences;
+}
+async function resolveLatestNoteIdsByTitles(db, userId, titles) {
+    const normalizedTitles = Array.from(new Set(titles
+        .map((title) => title.trim())
+        .filter((title) => title.length > 0)));
+    if (normalizedTitles.length === 0) {
+        return new Map();
+    }
+    const columns = await db.getAll('PRAGMA table_info(c_note)', []);
+    const columnNames = new Set(columns
+        .map((row) => row.name?.trim().toLowerCase() ?? '')
+        .filter((name) => name.length > 0));
+    const userColumns = [];
+    if (columnNames.has('user_id')) {
+        userColumns.push('user_id');
+    }
+    if (columnNames.has('user_no')) {
+        userColumns.push('user_no');
+    }
+    if (!columnNames.has('title') || !columnNames.has('id') || userColumns.length === 0) {
+        return new Map();
+    }
+    const userClauses = userColumns.map((column) => `n.${column} = ?`);
+    const titlePlaceholders = normalizedTitles.map(() => '?').join(', ');
+    const params = [...userColumns.map(() => userId), ...normalizedTitles];
+    const rows = await db.getAll(`
+    SELECT
+      n.id,
+      TRIM(n.title) AS title_key
+    FROM c_note n
+    WHERE (${userClauses.join(' OR ')})
+      AND (n.is_del IS NULL OR n.is_del = 0)
+      AND TRIM(n.title) IN (${titlePlaceholders})
+    ORDER BY title_key ASC, COALESCE(n.created_at, '') DESC, n.id DESC
+    `, params);
+    const resolved = new Map();
+    for (const row of rows) {
+        const titleKey = typeof row.title_key === 'string' ? row.title_key.trim() : '';
+        const id = typeof row.id === 'string' ? row.id.trim() : '';
+        if (!titleKey || !id || resolved.has(titleKey)) {
+            continue;
+        }
+        resolved.set(titleKey, id);
+    }
+    return resolved;
+}
+export async function canonicalizeBidlinksInMarkdown(db, markdown, userId) {
+    const source = typeof markdown === 'string' ? markdown : String(markdown ?? '');
+    if (!source.includes('[[') || !userId.trim()) {
+        return source;
+    }
+    const occurrences = collectBidlinkOccurrences(source);
+    if (occurrences.length === 0) {
+        return source;
+    }
+    const resolvedIdsByTitle = await resolveLatestNoteIdsByTitles(db, userId, occurrences.map((occurrence) => occurrence.label));
+    if (resolvedIdsByTitle.size === 0) {
+        return source;
+    }
+    let nextMarkdown = source;
+    const sorted = [...occurrences].sort((left, right) => right.startOffset - left.startOffset);
+    for (const occurrence of sorted) {
+        const resolvedId = resolvedIdsByTitle.get(occurrence.label);
+        if (!resolvedId) {
+            continue;
+        }
+        const replacement = `[[${escapeBidlinkValue(occurrence.label)}|${escapeBidlinkValue(resolvedId)}]]`;
+        nextMarkdown =
+            nextMarkdown.slice(0, occurrence.startOffset) +
+                replacement +
+                nextMarkdown.slice(occurrence.endOffset);
+    }
+    return nextMarkdown;
+}

package/dist/utils/dryRun.d.ts

@@ -0,0 +1,13 @@
+export type DryRunPreview = {
+    dry_run: true;
+    command: string;
+    action: string;
+    risk: 'write' | 'high-risk-write';
+    summary: string;
+    warnings?: string[];
+    inputs?: Record<string, unknown>;
+    targets?: Array<Record<string, unknown>>;
+    changes?: Record<string, unknown> | Array<Record<string, unknown>>;
+};
+export declare function formatDryRunPreview(preview: DryRunPreview): string;
+export declare function printDryRunPreview(preview: DryRunPreview): void;

package/dist/utils/dryRun.js

@@ -0,0 +1,69 @@
+import { getRequestedStructuredOutputFormat, printHumanReadableBlock, printSuccess, } from './output.js';
+function formatValue(value) {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function formatRecord(record, prefix = '  ') {
+    return Object.entries(record).map(([key, value]) => `${prefix}${key}: ${formatValue(value)}`);
+}
+function formatTargets(targets) {
+    const lines = [];
+    targets.forEach((target, index) => {
+        lines.push(`  [${index + 1}]`);
+        lines.push(...formatRecord(target, '    '));
+    });
+    return lines;
+}
+function formatChanges(value) {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return formatTargets(value);
+    }
+    return formatRecord(value);
+}
+export function formatDryRunPreview(preview) {
+    const lines = [
+        '=== Dry Run ===',
+        `Action: ${preview.action}`,
+        `Command: ${preview.command}`,
+        `Risk: ${preview.risk}`,
+        `Summary: ${preview.summary}`,
+    ];
+    if (preview.warnings && preview.warnings.length > 0) {
+        lines.push('');
+        lines.push('Warnings:');
+        for (const warning of preview.warnings) {
+            lines.push(`  - ${warning}`);
+        }
+    }
+    if (preview.inputs && Object.keys(preview.inputs).length > 0) {
+        lines.push('');
+        lines.push('Inputs:');
+        lines.push(...formatRecord(preview.inputs));
+    }
+    if (preview.targets && preview.targets.length > 0) {
+        lines.push('');
+        lines.push('Targets:');
+        lines.push(...formatTargets(preview.targets));
+    }
+    if (preview.changes && (Array.isArray(preview.changes) ? preview.changes.length > 0 : Object.keys(preview.changes).length > 0)) {
+        lines.push('');
+        lines.push('Changes:');
+        lines.push(...formatChanges(preview.changes));
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function printDryRunPreview(preview) {
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess(preview);
+        return;
+    }
+    printHumanReadableBlock(formatDryRunPreview(preview));
+}

package/dist/utils/output.d.ts

@@ -1,2 +1,21 @@
+export type StructuredOutputFormat = 'yaml' | 'json';
+export type StructuredNoticeMap = Record<string, unknown>;
 export declare function toYaml(value: unknown): string;
+export declare function toJson(value: unknown): string;
+export declare function printHumanReadableLine(text: string): void;
+export declare function printHumanReadableBlock(text: string): void;
+export declare function printHumanReadableError(text: string): void;
+export declare function resolveStructuredOutputFormat(input: {
+    format?: unknown;
+    json?: unknown;
+}): StructuredOutputFormat | null;
+export declare function parseStructuredOutputFormatFromArgv(argv: string[]): StructuredOutputFormat | null;
+export declare function setRequestedStructuredOutputFormat(format: StructuredOutputFormat | null): void;
+export declare function clearRequestedStructuredOutputFormat(): void;
+export declare function getRequestedStructuredOutputFormat(): StructuredOutputFormat | null;
+export declare function setPendingStructuredNoticeProvider(provider: (() => StructuredNoticeMap | null) | null): void;
+export declare function clearPendingStructuredNoticeProvider(): void;
+export declare function printStructuredData(value: unknown, format?: StructuredOutputFormat | null): void;
+export declare function printSuccess(value: unknown, format?: StructuredOutputFormat | null): void;
+export declare function printError(value: unknown, format?: StructuredOutputFormat | null): void;
 export declare function printYaml(value: unknown): void;

package/dist/utils/output.js

@@ -1,10 +1,164 @@
 import { stringify as stringifyYaml } from 'yaml';
+import { sanitizeForTerminal } from './terminalSanitization.js';
+let requestedStructuredOutputFormat = null;
+let pendingStructuredNoticeProvider = null;
 export function toYaml(value) {
     return stringifyYaml(value, {
         lineWidth: 0,
         indent: 2,
     });
 }
+export function toJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function writeToStdout(text) {
+    process.stdout.write(text);
+}
+function writeToStderr(text) {
+    process.stderr.write(text);
+}
+export function printHumanReadableLine(text) {
+    writeToStdout(`${sanitizeForTerminal(text)}\n`);
+}
+export function printHumanReadableBlock(text) {
+    writeToStdout(sanitizeForTerminal(text));
+}
+export function printHumanReadableError(text) {
+    writeToStderr(`${sanitizeForTerminal(text)}\n`);
+}
+function normalizeStructuredOutputFormat(value) {
+    if (typeof value !== 'string') {
+        throw new Error('--format must be one of: yaml, json');
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'yaml' || normalized === 'json') {
+        return normalized;
+    }
+    throw new Error('--format must be one of: yaml, json');
+}
+export function resolveStructuredOutputFormat(input) {
+    if (input.format !== undefined && input.format !== null && input.format !== '') {
+        return normalizeStructuredOutputFormat(input.format);
+    }
+    if (Boolean(input.json)) {
+        return 'yaml';
+    }
+    return null;
+}
+export function parseStructuredOutputFormatFromArgv(argv) {
+    let format = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg) {
+            continue;
+        }
+        if (arg === '--json') {
+            format = 'yaml';
+            continue;
+        }
+        if (arg === '--format') {
+            format = normalizeStructuredOutputFormat(argv[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--format=')) {
+            format = normalizeStructuredOutputFormat(arg.slice('--format='.length));
+        }
+    }
+    return format;
+}
+export function setRequestedStructuredOutputFormat(format) {
+    requestedStructuredOutputFormat = format;
+}
+export function clearRequestedStructuredOutputFormat() {
+    requestedStructuredOutputFormat = null;
+}
+export function getRequestedStructuredOutputFormat() {
+    return requestedStructuredOutputFormat;
+}
+export function setPendingStructuredNoticeProvider(provider) {
+    pendingStructuredNoticeProvider = provider;
+}
+export function clearPendingStructuredNoticeProvider() {
+    pendingStructuredNoticeProvider = null;
+}
+function getPendingStructuredNotice() {
+    if (!pendingStructuredNoticeProvider) {
+        return null;
+    }
+    return pendingStructuredNoticeProvider();
+}
+export function printStructuredData(value, format = getRequestedStructuredOutputFormat()) {
+    if (format === 'json') {
+        writeToStdout(toJson(value));
+        return;
+    }
+    writeToStdout(toYaml(value));
+}
+function normalizeSuccessEnvelopeData(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return value;
+    }
+    const record = value;
+    if (record.ok !== true) {
+        return value;
+    }
+    const { ok: _ignored, ...rest } = record;
+    return rest;
+}
+function deriveStructuredNotice(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const notice = {};
+    if (record.stale === true) {
+        notice.stale_cache = {
+            message: 'Result may be stale because the local cache did not fully synchronize.',
+        };
+    }
+    if (record.uploadEnabled === false) {
+        notice.upload_disabled = {
+            message: 'Local changes cannot upload because powersync.uploadBaseUrl is unset.',
+        };
+    }
+    return Object.keys(notice).length > 0 ? notice : null;
+}
+function mergeStructuredNotices(base, derived) {
+    const merged = {
+        ...(base ?? {}),
+        ...(derived ?? {}),
+    };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+export function printSuccess(value, format = getRequestedStructuredOutputFormat()) {
+    if (format === 'json') {
+        const data = normalizeSuccessEnvelopeData(value);
+        const notice = mergeStructuredNotices(getPendingStructuredNotice(), deriveStructuredNotice(data));
+        printStructuredData({
+            ok: true,
+            data,
+            ...(notice ? { _notice: notice } : {}),
+        }, 'json');
+        return;
+    }
+    printStructuredData(value, format);
+}
+export function printError(value, format = getRequestedStructuredOutputFormat()) {
+    if (format === 'json') {
+        const notice = getPendingStructuredNotice();
+        writeToStderr(toJson({
+            ok: false,
+            error: value,
+            ...(notice ? { _notice: notice } : {}),
+        }));
+        return;
+    }
+    writeToStdout(toYaml({
+        ok: false,
+        error: value,
+    }));
+}
 export function printYaml(value) {
-    process.stdout.write(toYaml(value));
+    printStructuredData(value);
 }

package/dist/utils/terminalSanitization.d.ts

@@ -0,0 +1,2 @@
+export declare function isDangerousUnicode(rune: number): boolean;
+export declare function sanitizeForTerminal(text: string): string;