@dinoxx/dinox-cli 2.0.0 → 2.1.1

package/dist/contract/snapshot.d.ts

@@ -0,0 +1,30 @@
+export type ContractOption = {
+    name: string;
+    required: boolean;
+    type?: string;
+    enum?: string[];
+};
+export type ContractCommand = {
+    path: string;
+    command: string;
+    risk: string;
+    auth: string;
+    arguments: Array<{
+        name: string;
+        required: boolean;
+    }>;
+    options: ContractOption[];
+    outputFields: string[];
+    outputMetaFields: string[];
+};
+export type CliContractSnapshot = {
+    contractVersion: 1;
+    cliVersion: string;
+    commands: ContractCommand[];
+    errorCodes: Record<string, number>;
+};
+export declare function buildContractSnapshot(cliVersion: string): CliContractSnapshot;
+export declare function renderContractSnapshot(snapshot: CliContractSnapshot): string;
+/** Changes that can break an existing agent or script that relied on the previous contract. */
+export declare function findBreakingChanges(previous: CliContractSnapshot, next: CliContractSnapshot): string[];
+export declare function majorVersion(version: string): number;

package/dist/contract/snapshot.js

@@ -0,0 +1,114 @@
+// Machine-readable snapshot of the agent-facing CLI contract: command paths, arguments,
+// options, risk/auth, structured output fields, and error codes with exit statuses.
+// The committed copy (contract/cli-contract.json) makes every contract change visible in
+// review, and `findBreakingChanges` refuses breaking changes without a major version bump.
+import { listCommandSchemas } from '../commands/schema/spec.js';
+import { ERROR_CODES } from '../utils/errorCodes.js';
+const RISK_ORDER = ['read', 'write', 'high-risk-write'];
+function flagOf(optionName) {
+    return optionName.match(/--[a-z0-9][a-z0-9-]*/i)?.[0] ?? optionName;
+}
+export function buildContractSnapshot(cliVersion) {
+    const commands = listCommandSchemas()
+        .map((schema) => ({
+        path: schema.path,
+        command: schema.command,
+        risk: schema.risk,
+        auth: schema.auth,
+        arguments: (schema.arguments ?? []).map((argument) => ({ name: argument.name, required: argument.required })),
+        options: (schema.options ?? [])
+            .map((option) => ({
+            name: option.name,
+            required: option.required === true,
+            ...(option.type ? { type: option.type } : {}),
+            ...(option.enum ? { enum: [...option.enum] } : {}),
+        }))
+            .sort((left, right) => flagOf(left.name).localeCompare(flagOf(right.name))),
+        outputFields: [...(schema.output.fields ?? [])],
+        outputMetaFields: [...(schema.output.metaFields ?? [])],
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+    const errorCodes = Object.fromEntries(Object.keys(ERROR_CODES).sort().map((code) => [code, ERROR_CODES[code].exitCode]));
+    return { contractVersion: 1, cliVersion, commands, errorCodes };
+}
+export function renderContractSnapshot(snapshot) {
+    return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+/** Changes that can break an existing agent or script that relied on the previous contract. */
+export function findBreakingChanges(previous, next) {
+    const changes = [];
+    const nextCommands = new Map(next.commands.map((command) => [command.path, command]));
+    for (const before of previous.commands) {
+        const after = nextCommands.get(before.path);
+        if (!after) {
+            changes.push(`command ${before.path} was removed`);
+            continue;
+        }
+        if (after.command !== before.command) {
+            changes.push(`command ${before.path} changed invocation from \`${before.command}\` to \`${after.command}\``);
+        }
+        if (RISK_ORDER.indexOf(after.risk) > RISK_ORDER.indexOf(before.risk)) {
+            changes.push(`command ${before.path} risk escalated from ${before.risk} to ${after.risk}`);
+        }
+        if (before.auth !== 'required' && after.auth === 'required') {
+            changes.push(`command ${before.path} now requires auth`);
+        }
+        const requiredArgsBefore = before.arguments.filter((argument) => argument.required).length;
+        const requiredArgsAfter = after.arguments.filter((argument) => argument.required).length;
+        if (requiredArgsAfter > requiredArgsBefore) {
+            changes.push(`command ${before.path} gained a required positional argument`);
+        }
+        if (after.arguments.length < before.arguments.length) {
+            changes.push(`command ${before.path} lost a positional argument`);
+        }
+        const optionsAfter = new Map(after.options.map((option) => [flagOf(option.name), option]));
+        for (const option of before.options) {
+            const flag = flagOf(option.name);
+            const updated = optionsAfter.get(flag);
+            if (!updated) {
+                changes.push(`option ${before.path} ${flag} was removed`);
+                continue;
+            }
+            if (!option.required && updated.required) {
+                changes.push(`option ${before.path} ${flag} became required`);
+            }
+            if (option.type && updated.type && option.type !== updated.type) {
+                changes.push(`option ${before.path} ${flag} changed type from ${option.type} to ${updated.type}`);
+            }
+            for (const value of option.enum ?? []) {
+                if (updated.enum && !updated.enum.includes(value)) {
+                    changes.push(`option ${before.path} ${flag} no longer accepts ${value}`);
+                }
+            }
+        }
+        for (const option of after.options) {
+            if (option.required && !before.options.some((previousOption) => flagOf(previousOption.name) === flagOf(option.name))) {
+                changes.push(`option ${before.path} ${flagOf(option.name)} was added as required`);
+            }
+        }
+        for (const field of before.outputFields) {
+            if (!after.outputFields.includes(field)) {
+                changes.push(`output field ${before.path}.${field} was removed`);
+            }
+        }
+        for (const field of before.outputMetaFields) {
+            if (!after.outputMetaFields.includes(field)) {
+                changes.push(`output meta field ${before.path}.${field} was removed`);
+            }
+        }
+    }
+    for (const [code, exitCode] of Object.entries(previous.errorCodes)) {
+        const updated = next.errorCodes[code];
+        if (updated === undefined) {
+            changes.push(`error code ${code} was removed`);
+        }
+        else if (updated !== exitCode) {
+            changes.push(`error code ${code} exit status changed from ${exitCode} to ${updated}`);
+        }
+    }
+    return changes;
+}
+export function majorVersion(version) {
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    return Number.isFinite(major) ? major : 0;
+}

package/dist/daemon/client.js

@@ -2,7 +2,7 @@ import { request as httpRequest } from 'node:http';
 import { existsSync } from 'node:fs';
 import { getDaemonSocketPath, isLegacyDaemonProcess, isProcessRunning, readPid, removePid, } from './pid.js';
 import { remainingDeadlineMs } from '../utils/deadline.js';
-import { DinoxError } from '../utils/errors.js';
+import { DinoxError, wireErrorCode } from '../utils/errors.js';
 const DEFAULT_DAEMON_REQUEST_TIMEOUT_MS = 10_000;
 const MAX_DAEMON_RESPONSE_BYTES = 5 * 1024 * 1024;
 function normalizedTimeoutMs(timeoutMs, fallbackMs) {
@@ -114,7 +114,7 @@ function toDaemonError(error) {
     if (isStructuredDaemonError(error)) {
         if (error.name === 'DinoxError' || error.code !== 'INTERNAL_ERROR') {
             return new DinoxError(error.message, {
-                code: error.code,
+                code: wireErrorCode(error.code),
                 details: error.details,
                 suggestion: error.suggestion,
                 suggestedAction: error.suggested_action,

package/dist/powersync/uploader.js

@@ -3,6 +3,7 @@ import { UpdateType } from '@powersync/common';
 import { createTimeoutSignal, mergeAbortSignals } from '../utils/abort.js';
 import { toAuthorizationHeaderValue } from '../utils/authToken.js';
 import { sanitizeForTerminal } from '../utils/terminalSanitization.js';
+import { nowIsoUtc } from '../utils/time.js';
 /**
  * Uploads each PowerSync CRUD transaction as ONE request to the backend v6 batch
  * endpoint (same contract as dinox-electron / dinox-web / dinox-app). The backend
@@ -23,6 +24,30 @@ const UPLOAD_REQUIRED_INSERT_DEFAULTS_BY_TABLE = new Map([
     // PowerSync omits NULL values from PUT payloads, while the backend requires these.
     ['c_note_template', { content: '', extra_data: '{}' }],
 ]);
+/**
+ * CLI 1.x kept star state in `c_note.is_starred`; 2.x, the other clients, and the v6
+ * backend use `starred_at`. 1.x operations still queued in the same local database
+ * survive the upgrade, and the backend rejects the unknown column, which blocks every
+ * later upload. Translate them the same way 2.x writes a star change.
+ */
+function translateLegacyNoteStar(table, values) {
+    if (table !== 'c_note' || !Object.prototype.hasOwnProperty.call(values, 'is_starred'))
+        return values;
+    const { is_starred: legacyStarred, ...rest } = values;
+    if (!Object.prototype.hasOwnProperty.call(rest, 'starred_at')) {
+        const starred = legacyStarred === 1 || legacyStarred === true || legacyStarred === '1';
+        rest.starred_at = starred
+            ? (typeof rest.updated_at === 'string' && rest.updated_at ? rest.updated_at : nowIsoUtc())
+            : null;
+    }
+    return rest;
+}
+function dropLegacyColumns(table, values) {
+    if (!values || table !== 'c_note' || !('is_starred' in values))
+        return values;
+    const { is_starred: _legacyStarred, ...rest } = values;
+    return rest;
+}
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -94,9 +119,9 @@ export function toUploadOperation(op) {
         type: table,
         id: String(op.id),
         ...(op.transactionId !== undefined ? { tx_id: op.transactionId } : {}),
-        ...(data ? { data: omitColumns(table, data) } : {}),
+        ...(data ? { data: omitColumns(table, translateLegacyNoteStar(table, data)) } : {}),
         // DELETE needs no base: deletes win (PowerSync default), nothing to compare.
-        ...(name === 'PATCH' ? compactPreviousValues(op.previousValues) : {}),
+        ...(name === 'PATCH' ? compactPreviousValues(dropLegacyColumns(table, op.previousValues)) : {}),
         ...(op.metadata !== undefined ? { metadata: op.metadata } : {}),
     };
 }

package/dist/skills/commandRefs.d.ts

@@ -0,0 +1,21 @@
+import { type CommandSchema } from '../commands/schema/spec.js';
+export type SkillCommandReferenceIssue = {
+    /** Path relative to the skills directory. */
+    file: string;
+    line: number;
+    snippet: string;
+    message: string;
+};
+type CommandIndex = {
+    byCommand: Map<string, CommandSchema>;
+    groups: Set<string>;
+};
+/** Extracts `dino ...` invocations from inline code spans and fenced code block lines. */
+export declare function extractDinoInvocations(markdown: string): Array<{
+    line: number;
+    text: string;
+}>;
+export declare function validateDinoInvocation(text: string, index?: CommandIndex): string | null;
+/** Verifies that every `dino ...` invocation in the skill markdown resolves against the command schemas. */
+export declare function checkSkillCommandReferences(skillsDir: string): SkillCommandReferenceIssue[];
+export {};

package/dist/skills/commandRefs.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listCommandSchemas } from '../commands/schema/spec.js';
+// Global flags accepted by every command (see src/cli.ts) plus Commander builtins.
+const GLOBAL_FLAGS = new Set([
+    '--json',
+    '--format',
+    '--offline',
+    '--require-sync',
+    '--sync-timeout',
+    '--verbose',
+    '--help',
+    '--version',
+]);
+const SHELL_BOUNDARY = /\s(?:\||&&|\|\||;|>|2>|#)\s/;
+function buildCommandIndex() {
+    const byCommand = new Map();
+    const groups = new Set();
+    for (const schema of listCommandSchemas()) {
+        const words = schema.command.split(/\s+/).slice(1);
+        byCommand.set(words.join(' '), schema);
+        if (words.length > 1) {
+            groups.add(words[0]);
+        }
+    }
+    return { byCommand, groups };
+}
+function optionFlags(schema) {
+    const flags = new Set();
+    for (const option of schema.options ?? []) {
+        for (const match of option.name.matchAll(/--[a-z0-9][a-z0-9-]*/gi)) {
+            flags.add(match[0]);
+        }
+    }
+    return flags;
+}
+/** Extracts `dino ...` invocations from inline code spans and fenced code block lines. */
+export function extractDinoInvocations(markdown) {
+    const invocations = [];
+    const lines = markdown.split(/\r?\n/);
+    let inFence = false;
+    lines.forEach((rawLine, index) => {
+        const lineNumber = index + 1;
+        if (/^\s*(```|~~~)/.test(rawLine)) {
+            inFence = !inFence;
+            return;
+        }
+        if (inFence) {
+            const match = rawLine.match(/(?:^|\s|\$\s*)(dino\s+[^`]*)$/);
+            if (match?.[1]) {
+                invocations.push({ line: lineNumber, text: match[1] });
+            }
+            return;
+        }
+        for (const match of rawLine.matchAll(/`(dino\s+[^`]+)`/g)) {
+            if (match[1]) {
+                invocations.push({ line: lineNumber, text: match[1] });
+            }
+        }
+    });
+    return invocations;
+}
+export function validateDinoInvocation(text, index = buildCommandIndex()) {
+    const command = text.split(SHELL_BOUNDARY)[0]?.trim() ?? '';
+    const tokens = command.split(/\s+/).slice(1);
+    const first = tokens[0];
+    // Placeholders such as `dino <command>` or `dino ...` are prose, not invocations.
+    if (!first || !/^[a-z][a-z0-9-]*$/.test(first)) {
+        return null;
+    }
+    let schema;
+    let consumed = 0;
+    for (let length = Math.min(tokens.length, 3); length >= 1; length -= 1) {
+        const candidate = index.byCommand.get(tokens.slice(0, length).join(' '));
+        if (candidate) {
+            schema = candidate;
+            consumed = length;
+            break;
+        }
+    }
+    if (!schema) {
+        const second = tokens[1];
+        if (index.groups.has(first) && (!second || !/^[a-z][a-z0-9-]*$/.test(second))) {
+            return null;
+        }
+        return `unknown command \`dino ${tokens.slice(0, index.groups.has(first) ? 2 : 1).join(' ')}\``;
+    }
+    const known = optionFlags(schema);
+    for (const token of tokens.slice(consumed)) {
+        const flag = token.match(/^(--[a-z0-9][a-z0-9-]*)/i)?.[1];
+        if (!flag || GLOBAL_FLAGS.has(flag) || known.has(flag)) {
+            continue;
+        }
+        return `\`${schema.command}\` has no option \`${flag}\``;
+    }
+    return null;
+}
+function listMarkdownFiles(dir) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listMarkdownFiles(fullPath));
+        }
+        else if (entry.name.endsWith('.md')) {
+            files.push(fullPath);
+        }
+    }
+    return files.sort();
+}
+/** Verifies that every `dino ...` invocation in the skill markdown resolves against the command schemas. */
+export function checkSkillCommandReferences(skillsDir) {
+    const index = buildCommandIndex();
+    const issues = [];
+    for (const filePath of listMarkdownFiles(skillsDir)) {
+        const markdown = fs.readFileSync(filePath, 'utf8');
+        for (const invocation of extractDinoInvocations(markdown)) {
+            const message = validateDinoInvocation(invocation.text, index);
+            if (message) {
+                issues.push({
+                    file: path.relative(skillsDir, filePath).split(path.sep).join('/'),
+                    line: invocation.line,
+                    snippet: invocation.text.trim(),
+                    message,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/dist/skills/generate.d.ts

@@ -0,0 +1,13 @@
+import { type GeneratedSkillSection } from './registry.js';
+export type GeneratedSkillFile = {
+    skill: string;
+    /** Path relative to the skills directory. */
+    file: string;
+    marker: GeneratedSkillSection['marker'] | 'PORTABLE_RUNTIME';
+    render: () => string;
+};
+/** Every generated block in the published skill set, derived from the skill registry. */
+export declare function listGeneratedSkillFiles(): GeneratedSkillFile[];
+export declare function syncGeneratedSkills(skillsDir: string): void;
+/** Returns human-readable issues; empty when every generated block is current. */
+export declare function checkGeneratedSkills(skillsDir: string): string[];

package/dist/skills/generate.js

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listGeneratedCommandSectionKeys, renderBundledSkillReference, renderErrorCodeReference, renderGeneratedCommandSection, renderPortableRuntimeContract, replaceGeneratedSection, } from '../commands/schema/renderSkills.js';
+import { SKILL_REGISTRY } from './registry.js';
+/** Every generated block in the published skill set, derived from the skill registry. */
+export function listGeneratedSkillFiles() {
+    const files = [];
+    for (const entry of SKILL_REGISTRY) {
+        files.push({
+            skill: entry.name,
+            file: `${entry.name}/SKILL.md`,
+            marker: 'PORTABLE_RUNTIME',
+            render: renderPortableRuntimeContract,
+        });
+        for (const section of entry.generated) {
+            const key = section.key;
+            if (section.marker === 'GENERATED_COMMANDS' && !key) {
+                throw new Error(`${entry.name}/${section.file} GENERATED_COMMANDS section is missing a key`);
+            }
+            files.push({
+                skill: entry.name,
+                file: `${entry.name}/${section.file}`,
+                marker: section.marker,
+                render: section.marker === 'GENERATED_REFERENCE'
+                    ? renderBundledSkillReference
+                    : section.marker === 'GENERATED_ERRORS'
+                        ? renderErrorCodeReference
+                        : () => renderGeneratedCommandSection(key),
+            });
+        }
+    }
+    return files;
+}
+function applyGeneratedBlock(skillsDir, generated) {
+    const filePath = path.join(skillsDir, generated.file);
+    const current = fs.readFileSync(filePath, 'utf8');
+    return { current, next: replaceGeneratedSection(current, generated.marker, generated.render()) };
+}
+export function syncGeneratedSkills(skillsDir) {
+    for (const generated of listGeneratedSkillFiles()) {
+        const { current, next } = applyGeneratedBlock(skillsDir, generated);
+        if (next !== current) {
+            fs.writeFileSync(path.join(skillsDir, generated.file), next);
+        }
+    }
+}
+/** Returns human-readable issues; empty when every generated block is current. */
+export function checkGeneratedSkills(skillsDir) {
+    const issues = [];
+    const usedKeys = new Set();
+    for (const entry of SKILL_REGISTRY) {
+        for (const section of entry.generated) {
+            if (section.key) {
+                if (usedKeys.has(section.key)) {
+                    issues.push(`generated section key ${section.key} is used more than once`);
+                }
+                usedKeys.add(section.key);
+            }
+        }
+    }
+    for (const key of listGeneratedCommandSectionKeys()) {
+        if (!usedKeys.has(key)) {
+            issues.push(`generated section ${key} is configured but not registered for any skill file`);
+        }
+    }
+    for (const generated of listGeneratedSkillFiles()) {
+        let result;
+        try {
+            result = applyGeneratedBlock(skillsDir, generated);
+        }
+        catch (error) {
+            issues.push(`${generated.file}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (result.current !== result.next) {
+            issues.push(`${generated.file} ${generated.marker} block is stale; run pnpm skills:sync`);
+        }
+    }
+    return issues;
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,13 @@
+export type GeneratedSkillSection = Readonly<{
+    /** File path relative to the skill directory. */
+    file: string;
+    marker: 'GENERATED_COMMANDS' | 'GENERATED_REFERENCE' | 'GENERATED_ERRORS';
+    /** Section key in renderSkills; required for GENERATED_COMMANDS. */
+    key?: string;
+}>;
+export type SkillRegistryEntry = Readonly<{
+    name: string;
+    generated: readonly GeneratedSkillSection[];
+}>;
+export declare const SKILL_REGISTRY: readonly SkillRegistryEntry[];
+export declare function listRegisteredSkillNames(): string[];

package/dist/skills/registry.js

@@ -0,0 +1,58 @@
+// Single source of truth for the published Dinox skill set. Generation
+// (`pnpm skills:sync`), validation (`pnpm skills:check`), tests, and the
+// collection manifest all derive their skill lists from this registry.
+function commands(file, key) {
+    return Object.freeze({ file, marker: 'GENERATED_COMMANDS', key });
+}
+const REGISTRY_ENTRIES = [
+    { name: 'dino-auth', generated: [] },
+    { name: 'dino-config', generated: [] },
+    {
+        name: 'dino-dinox',
+        generated: [
+            { file: 'references/commands.md', marker: 'GENERATED_REFERENCE' },
+            { file: 'references/errors.md', marker: 'GENERATED_ERRORS' },
+        ],
+    },
+    {
+        name: 'dino-manage-boxes',
+        generated: [commands('SKILL.md', 'skill:dino-manage-boxes')],
+    },
+    {
+        name: 'dino-manage-prompts',
+        generated: [commands('SKILL.md', 'skill:dino-manage-prompts')],
+    },
+    {
+        name: 'dino-manage-tags',
+        generated: [commands('SKILL.md', 'skill:dino-manage-tags')],
+    },
+    {
+        name: 'dino-manage-todo',
+        generated: [
+            commands('references/todo-search.md', 'ref:dino-manage-todo:todo-search'),
+            commands('references/todo-mutations.md', 'ref:dino-manage-todo:todo-mutations'),
+        ],
+    },
+    {
+        name: 'dino-manage-views',
+        generated: [commands('SKILL.md', 'skill:dino-manage-views')],
+    },
+    {
+        name: 'dino-note',
+        generated: [
+            commands('references/search-and-read.md', 'ref:dino-note:search-and-read'),
+            commands('references/create.md', 'ref:dino-note:create'),
+            commands('references/update-and-delete.md', 'ref:dino-note:update-and-delete'),
+        ],
+    },
+    {
+        name: 'dino-storage',
+        generated: [commands('SKILL.md', 'skill:dino-storage')],
+    },
+    { name: 'dino-sync', generated: [] },
+    { name: 'dino-update-cli', generated: [] },
+];
+export const SKILL_REGISTRY = Object.freeze(REGISTRY_ENTRIES.map((entry) => Object.freeze({ ...entry, generated: Object.freeze([...entry.generated]) })));
+export function listRegisteredSkillNames() {
+    return SKILL_REGISTRY.map((entry) => entry.name);
+}