@dinoxx/dinox-cli 1.1.1 → 2.1.0

package/dist/commands/skills/index.js

@@ -0,0 +1,572 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { getSkillsReleaseMetadata, SKILLS_INSTALL_AGENTS, SKILLS_INSTALLER_NAME, SKILLS_INSTALLER_VERSION, SKILLS_REPO_SLUG, } from '../../constants/links.js';
+import { listRegisteredSkillNames } from '../../skills/registry.js';
+import { RETIRED_SKILLS } from '../../skills/retired.js';
+import { getPackageVersion } from '../../utils/version.js';
+import { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { FORMAT_OPTIONS } from '../schema/globalOptions.js';
+const MAX_CAPTURED_INSTALLER_OUTPUT_BYTES = 64 * 1024;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function defaultLockFilePath() {
+    return path.join(homedir(), '.agents', '.skill-lock.json');
+}
+async function defaultReadLockFile(lockFilePath) {
+    return readFile(lockFilePath, 'utf8');
+}
+function absentScan(lockFilePath) {
+    const skills = RETIRED_SKILLS.map((skill) => ({
+        name: skill.name,
+        replacement: skill.replacement,
+        ...('replacementNote' in skill ? { replacementNote: skill.replacementNote } : {}),
+        status: 'absent',
+        expected: {
+            source: skill.source,
+            skillFolderHash: skill.skillFolderHash,
+        },
+        observed: null,
+        mismatches: [],
+    }));
+    return {
+        lockFile: lockFilePath,
+        lockFound: false,
+        lockVersion: null,
+        summary: {
+            total: skills.length,
+            absent: skills.length,
+            safeToRemove: 0,
+            conflict: 0,
+        },
+        skills,
+    };
+}
+function invalidLockError(lockFilePath, message, cause) {
+    return new DinoxError(`Invalid skills installer lock at ${lockFilePath}: ${message}`, {
+        code: 'SKILLS_LOCK_INVALID',
+        cause,
+        details: { lockFile: lockFilePath },
+        suggestion: 'Inspect the lock file without deleting it, then rerun `dino skills doctor --format json`.',
+        recoverable: true,
+    });
+}
+async function readSkillsLock(lockFilePath, readLockFile) {
+    let raw;
+    try {
+        raw = await readLockFile(lockFilePath);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return { found: false, version: null, entries: {} };
+        }
+        throw new DinoxError(`Failed to read skills installer lock at ${lockFilePath}`, {
+            code: 'SKILLS_LOCK_READ_FAILED',
+            cause: error,
+            details: { lockFile: lockFilePath },
+            suggestion: 'Check file permissions, then rerun `dino skills doctor --format json`.',
+            recoverable: true,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw invalidLockError(lockFilePath, 'file is not valid JSON', error);
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.skills)) {
+        throw invalidLockError(lockFilePath, 'expected an object with a skills map');
+    }
+    return {
+        found: true,
+        version: typeof parsed.version === 'number' ? parsed.version : null,
+        entries: parsed.skills,
+    };
+}
+export async function scanRetiredSkillsLock(lockFilePath = defaultLockFilePath(), readLockFile = defaultReadLockFile) {
+    const lock = await readSkillsLock(lockFilePath, readLockFile);
+    if (!lock.found) {
+        return absentScan(lockFilePath);
+    }
+    return scanRetiredSkills(lockFilePath, lock);
+}
+function scanRetiredSkills(lockFilePath, lock) {
+    const entries = lock.entries;
+    const skills = RETIRED_SKILLS.map((skill) => {
+        if (!Object.prototype.hasOwnProperty.call(entries, skill.name)) {
+            return {
+                name: skill.name,
+                replacement: skill.replacement,
+                ...('replacementNote' in skill ? { replacementNote: skill.replacementNote } : {}),
+                status: 'absent',
+                expected: {
+                    source: skill.source,
+                    skillFolderHash: skill.skillFolderHash,
+                },
+                observed: null,
+                mismatches: [],
+            };
+        }
+        const rawEntry = entries[skill.name];
+        const entry = isRecord(rawEntry) ? rawEntry : {};
+        const observed = {
+            source: typeof entry.source === 'string' ? entry.source : null,
+            skillFolderHash: typeof entry.skillFolderHash === 'string' ? entry.skillFolderHash : null,
+        };
+        const mismatches = [];
+        if (observed.source !== skill.source)
+            mismatches.push('source');
+        if (observed.skillFolderHash !== skill.skillFolderHash)
+            mismatches.push('skillFolderHash');
+        return {
+            name: skill.name,
+            replacement: skill.replacement,
+            ...('replacementNote' in skill ? { replacementNote: skill.replacementNote } : {}),
+            status: mismatches.length === 0 ? 'safe-to-remove' : 'conflict',
+            expected: {
+                source: skill.source,
+                skillFolderHash: skill.skillFolderHash,
+            },
+            observed,
+            mismatches,
+        };
+    });
+    return {
+        lockFile: lockFilePath,
+        lockFound: true,
+        lockVersion: lock.version,
+        summary: {
+            total: skills.length,
+            absent: skills.filter((skill) => skill.status === 'absent').length,
+            safeToRemove: skills.filter((skill) => skill.status === 'safe-to-remove').length,
+            conflict: skills.filter((skill) => skill.status === 'conflict').length,
+        },
+        skills,
+    };
+}
+function readSkillVersion(skillMarkdown) {
+    const frontmatter = skillMarkdown.replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/)?.[1];
+    if (!frontmatter)
+        return null;
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatter);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const metadataVersion = isRecord(parsed.metadata) ? parsed.metadata.version : undefined;
+    // Skills before 2.0 used a vendor-specific top-level `version`.
+    const version = metadataVersion ?? parsed.version;
+    return typeof version === 'string' && version.trim() ? version.trim() : null;
+}
+/**
+ * Compares installed current Dinox skills against the skill set shipped with this CLI version.
+ * Installed skill files are read from the installer's canonical directory next to its lock.
+ */
+export async function scanCurrentSkills(lockFilePath = defaultLockFilePath(), readLockFile = defaultReadLockFile, readInstalledSkill = defaultReadLockFile, expectedVersion = getPackageVersion()) {
+    const lock = await readSkillsLock(lockFilePath, readLockFile);
+    const skillsRoot = path.join(path.dirname(lockFilePath), 'skills');
+    const skills = [];
+    for (const name of listRegisteredSkillNames()) {
+        const rawEntry = Object.prototype.hasOwnProperty.call(lock.entries, name) ? lock.entries[name] : undefined;
+        if (rawEntry === undefined) {
+            skills.push({ name, status: 'missing', source: null, installedVersion: null });
+            continue;
+        }
+        const source = isRecord(rawEntry) && typeof rawEntry.source === 'string' ? rawEntry.source : null;
+        if (source !== SKILLS_REPO_SLUG) {
+            skills.push({ name, status: 'foreign', source, installedVersion: null });
+            continue;
+        }
+        let installedVersion = null;
+        try {
+            installedVersion = readSkillVersion(await readInstalledSkill(path.join(skillsRoot, name, 'SKILL.md')));
+        }
+        catch {
+            installedVersion = null;
+        }
+        skills.push({
+            name,
+            status: installedVersion === null
+                ? 'unknown-version'
+                : installedVersion === expectedVersion ? 'current' : 'outdated',
+            source,
+            installedVersion,
+        });
+    }
+    const count = (status) => skills.filter((skill) => skill.status === status).length;
+    const summary = {
+        total: skills.length,
+        current: count('current'),
+        outdated: count('outdated'),
+        missing: count('missing'),
+        foreign: count('foreign'),
+        'unknown-version': count('unknown-version'),
+    };
+    return {
+        expectedVersion,
+        installCommand: getSkillsReleaseMetadata(expectedVersion).installCommand,
+        inSync: summary.current === summary.total,
+        summary,
+        skills,
+    };
+}
+function appendBoundedOutput(current, chunk) {
+    const currentBytes = Buffer.byteLength(current, 'utf8');
+    if (currentBytes >= MAX_CAPTURED_INSTALLER_OUTPUT_BYTES)
+        return current;
+    const remaining = MAX_CAPTURED_INSTALLER_OUTPUT_BYTES - currentBytes;
+    return current + chunk.subarray(0, remaining).toString('utf8');
+}
+export function resolveSkillsRemoveInvocation(skillNames, platform = process.platform) {
+    const args = [
+        '--yes',
+        `${SKILLS_INSTALLER_NAME}@${SKILLS_INSTALLER_VERSION}`,
+        'remove',
+        '-g',
+        ...SKILLS_INSTALL_AGENTS.flatMap((agent) => ['-a', agent]),
+        '--skill',
+        ...skillNames,
+        '-y',
+    ];
+    const displayCommand = ['npx', ...args].join(' ');
+    if (platform === 'win32') {
+        return {
+            command: ['npx.cmd', ...args].join(' '),
+            args: [],
+            shell: true,
+            displayCommand,
+        };
+    }
+    return {
+        command: 'npx',
+        args,
+        shell: false,
+        displayCommand,
+    };
+}
+export function runSkillsRemoval(skillNames) {
+    const invocation = resolveSkillsRemoveInvocation(skillNames);
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const child = spawn(invocation.command, invocation.args, {
+            shell: invocation.shell,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout.on('data', (chunk) => {
+            stdout = appendBoundedOutput(stdout, chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr = appendBoundedOutput(stderr, chunk);
+        });
+        child.once('error', (error) => {
+            reject(new DinoxError(`Failed to start the skills installer: ${error.message}`, {
+                code: 'SKILLS_MIGRATION_FAILED',
+                cause: error,
+                details: {
+                    command: invocation.displayCommand,
+                },
+                suggestion: 'Verify that Node.js and npx are available, then rerun `dino skills migrate --confirm --format json`.',
+                recoverable: true,
+            }));
+        });
+        child.once('close', (exitCode) => {
+            resolve({ invocation, exitCode, stdout, stderr });
+        });
+    });
+}
+function resolveDependencies(overrides) {
+    return {
+        getLockFilePath: defaultLockFilePath,
+        readLockFile: defaultReadLockFile,
+        readInstalledSkill: defaultReadLockFile,
+        getExpectedVersion: getPackageVersion,
+        runRemoval: runSkillsRemoval,
+        ...overrides,
+    };
+}
+function replacementLabel(skill) {
+    if (skill.replacement)
+        return skill.replacement;
+    return skill.replacementNote ?? 'no direct replacement';
+}
+function printScan(scan) {
+    printHumanReadableLine(`skills lock: ${scan.lockFile} (${scan.lockFound ? 'found' : 'not found'})`);
+    for (const skill of scan.skills) {
+        if (skill.status === 'conflict') {
+            printHumanReadableLine(`${skill.name}: conflict; replacement: ${replacementLabel(skill)}; observed source=${skill.observed?.source ?? 'missing'} hash=${skill.observed?.skillFolderHash ?? 'missing'}`);
+            continue;
+        }
+        printHumanReadableLine(`${skill.name}: ${skill.status}; replacement: ${replacementLabel(skill)}`);
+    }
+    printHumanReadableLine(`summary: safe-to-remove=${scan.summary.safeToRemove} conflict=${scan.summary.conflict} absent=${scan.summary.absent}`);
+}
+function printCurrentScan(current) {
+    printHumanReadableLine(`current skills (expected ${current.expectedVersion}):`);
+    for (const skill of current.skills) {
+        const version = skill.installedVersion ? ` installed=${skill.installedVersion}` : '';
+        const source = skill.status === 'foreign' ? ` source=${skill.source ?? 'missing'}` : '';
+        printHumanReadableLine(`${skill.name}: ${skill.status}${version}${source}`);
+    }
+    if (!current.inSync) {
+        printHumanReadableLine(`to install the matching skills, run: ${current.installCommand}`);
+    }
+}
+function installerPayload(skillNames) {
+    return {
+        name: SKILLS_INSTALLER_NAME,
+        version: SKILLS_INSTALLER_VERSION,
+        scope: 'global',
+        agents: [...SKILLS_INSTALL_AGENTS],
+        command: skillNames.length > 0
+            ? resolveSkillsRemoveInvocation(skillNames).displayCommand
+            : null,
+    };
+}
+function safeSkillNames(scan) {
+    return scan.skills
+        .filter((skill) => skill.status === 'safe-to-remove')
+        .map((skill) => skill.name);
+}
+function conflictSkillNames(scan) {
+    return scan.skills
+        .filter((skill) => skill.status === 'conflict')
+        .map((skill) => skill.name);
+}
+function scanStatus(scan, name) {
+    return scan.skills.find((skill) => skill.name === name)?.status ?? null;
+}
+async function rescanForVerification(dependencies, lockFilePath) {
+    try {
+        return await scanRetiredSkillsLock(lockFilePath, dependencies.readLockFile);
+    }
+    catch (error) {
+        throw new DinoxError('Failed to verify the retired skills migration', {
+            code: 'SKILLS_MIGRATION_VERIFICATION_FAILED',
+            cause: error,
+            details: { lockFile: lockFilePath },
+            suggestion: 'Run `dino skills doctor --format json` and inspect the lock before retrying.',
+            recoverable: true,
+        });
+    }
+}
+export function createSkillsCommandGroup(overrides = {}) {
+    const dependencies = resolveDependencies(overrides);
+    return {
+        name: 'skills',
+        description: 'Inspect installed Dinox agent skills and safely migrate retired ones',
+        commands: [
+            {
+                name: 'doctor',
+                description: 'Check installed Dinox skills against this CLI version and find safely removable retired skills',
+                schema: {
+                    path: 'skills.doctor',
+                    risk: 'read',
+                    auth: 'none',
+                    globalOptions: FORMAT_OPTIONS,
+                    output: {
+                        type: 'structured',
+                        summary: 'Retired skill status (summary, skills) and current skill version drift (current) from the global skills installer lock',
+                        fields: ['lockFile', 'lockFound', 'lockVersion', 'summary', 'skills', 'current'],
+                    },
+                    examples: ['dino skills doctor', 'dino skills doctor --format json'],
+                },
+                action: async (_context) => {
+                    const lockFilePath = dependencies.getLockFilePath();
+                    const scan = await scanRetiredSkillsLock(lockFilePath, dependencies.readLockFile);
+                    const current = await scanCurrentSkills(lockFilePath, dependencies.readLockFile, dependencies.readInstalledSkill, dependencies.getExpectedVersion());
+                    const report = { ...scan, current };
+                    if (getRequestedStructuredOutputFormat()) {
+                        printSuccess(report);
+                        return;
+                    }
+                    printScan(scan);
+                    printCurrentScan(current);
+                },
+            },
+            {
+                name: 'migrate',
+                description: 'Preview or confirm safe removal of retired Dinox skills',
+                options: [
+                    {
+                        flags: '--dry-run',
+                        description: 'Preview safe removals without changing installed skills (default)',
+                        type: 'boolean',
+                    },
+                    {
+                        flags: '--confirm',
+                        description: 'Execute the reviewed migration using the pinned public skills installer',
+                        type: 'boolean',
+                    },
+                ],
+                schema: {
+                    path: 'skills.migrate',
+                    risk: 'high-risk-write',
+                    auth: 'none',
+                    globalOptions: FORMAT_OPTIONS,
+                    output: {
+                        type: 'structured',
+                        summary: 'Retired skill migration plan or verified removal result',
+                        fields: [
+                            'mode',
+                            'confirmed',
+                            'installer',
+                            'before',
+                            'plannedRemoval',
+                            'conflicts',
+                            'removed',
+                            'after',
+                            'verified',
+                        ],
+                    },
+                    examples: [
+                        'dino skills migrate --dry-run --format json',
+                        'dino skills migrate --confirm --format json',
+                    ],
+                },
+                action: async (context) => {
+                    const explicitDryRun = Boolean(context.options.dryRun);
+                    const confirmed = Boolean(context.options.confirm);
+                    if (explicitDryRun && confirmed) {
+                        throw new DinoxError('--dry-run cannot be used together with --confirm', {
+                            code: 'USAGE_ERROR',
+                            suggestion: 'Run `dino skills migrate --dry-run --format json`, review the plan, then rerun with `--confirm`.',
+                            recoverable: true,
+                        });
+                    }
+                    const lockFilePath = dependencies.getLockFilePath();
+                    const before = await scanRetiredSkillsLock(lockFilePath, dependencies.readLockFile);
+                    const plannedRemoval = safeSkillNames(before);
+                    const conflicts = conflictSkillNames(before);
+                    const installer = installerPayload(plannedRemoval);
+                    if (!confirmed) {
+                        const payload = {
+                            mode: 'dry-run',
+                            confirmed: false,
+                            installer,
+                            before,
+                            plannedRemoval,
+                            conflicts,
+                            removed: [],
+                            after: null,
+                            verified: false,
+                        };
+                        if (getRequestedStructuredOutputFormat()) {
+                            printSuccess(payload);
+                            return;
+                        }
+                        printHumanReadableLine('mode: dry-run');
+                        printScan(before);
+                        printHumanReadableLine(`would remove: ${plannedRemoval.join(', ') || 'none'}`);
+                        printHumanReadableLine('no changes made; use --confirm only after reviewing this plan');
+                        return;
+                    }
+                    if (plannedRemoval.length === 0) {
+                        const after = await rescanForVerification(dependencies, lockFilePath);
+                        const payload = {
+                            mode: 'migrate',
+                            confirmed: true,
+                            installer,
+                            before,
+                            plannedRemoval,
+                            conflicts,
+                            removed: [],
+                            after,
+                            verified: true,
+                        };
+                        if (getRequestedStructuredOutputFormat()) {
+                            printSuccess(payload);
+                            return;
+                        }
+                        printHumanReadableLine('mode: migrate');
+                        printScan(after);
+                        printHumanReadableLine('removed: none');
+                        printHumanReadableLine('verified: yes');
+                        return;
+                    }
+                    const preExecution = await scanRetiredSkillsLock(lockFilePath, dependencies.readLockFile);
+                    const changedCandidates = plannedRemoval.filter((name) => scanStatus(preExecution, name) !== 'safe-to-remove');
+                    if (changedCandidates.length > 0) {
+                        throw new DinoxError('The skills installer lock changed before migration execution', {
+                            code: 'SKILLS_MIGRATION_PRECONDITION_FAILED',
+                            exitCode: 5,
+                            details: {
+                                lockFile: lockFilePath,
+                                changedCandidates,
+                                before,
+                                preExecution,
+                            },
+                            suggestion: 'Run `dino skills doctor --format json`, review the new status, then retry the migration.',
+                            recoverable: true,
+                        });
+                    }
+                    const execution = await dependencies.runRemoval(plannedRemoval);
+                    const after = await rescanForVerification(dependencies, lockFilePath);
+                    if (execution.exitCode !== 0) {
+                        throw new DinoxError(`The skills installer exited with code ${execution.exitCode ?? 'unknown'}`, {
+                            code: 'SKILLS_MIGRATION_FAILED',
+                            details: {
+                                command: execution.invocation.displayCommand,
+                                exitCode: execution.exitCode,
+                                ...(execution.stdout.trim() ? { stdout: execution.stdout.trim() } : {}),
+                                ...(execution.stderr.trim() ? { stderr: execution.stderr.trim() } : {}),
+                                after,
+                            },
+                            suggestion: 'Run `dino skills doctor --format json` before deciding whether to retry.',
+                            recoverable: true,
+                        });
+                    }
+                    const remainingCandidates = plannedRemoval.filter((name) => scanStatus(after, name) !== 'absent');
+                    const unexpectedlyRemovedConflicts = conflicts.filter((name) => scanStatus(after, name) === 'absent');
+                    if (remainingCandidates.length > 0 || unexpectedlyRemovedConflicts.length > 0) {
+                        throw new DinoxError('Retired skills migration verification failed', {
+                            code: 'SKILLS_MIGRATION_VERIFICATION_FAILED',
+                            details: {
+                                command: execution.invocation.displayCommand,
+                                remainingCandidates,
+                                unexpectedlyRemovedConflicts,
+                                before,
+                                after,
+                            },
+                            suggestion: 'Run `dino skills doctor --format json` and inspect every conflict before taking further action.',
+                            recoverable: true,
+                        });
+                    }
+                    const payload = {
+                        mode: 'migrate',
+                        confirmed: true,
+                        installer,
+                        before,
+                        plannedRemoval,
+                        conflicts,
+                        removed: [...plannedRemoval],
+                        after,
+                        verified: true,
+                    };
+                    if (getRequestedStructuredOutputFormat()) {
+                        printSuccess(payload);
+                        return;
+                    }
+                    printHumanReadableLine('mode: migrate');
+                    printHumanReadableLine(`removed: ${plannedRemoval.join(', ')}`);
+                    printHumanReadableLine(`conflicts preserved: ${conflicts.join(', ') || 'none'}`);
+                    printHumanReadableLine('verified: yes');
+                },
+            },
+        ],
+    };
+}
+export const skillsCommandGroup = createSkillsCommandGroup();
+export function registerSkillsCommands(program, overrides = {}) {
+    registerCommandGroup(program, createSkillsCommandGroup(overrides));
+}

package/dist/commands/storage/index.js

@@ -53,7 +53,7 @@ async function runStorageUpload(context) {
                 storageUrl: plan.storageUrl,
                 selectionSource: plan.selectionSource,
                 overwrite: options.overwrite === true,
-            }));
+            }), runtime);
             return;
         }
         const result = await uploadFileToStorage(db, {
@@ -117,7 +117,7 @@ async function runStorageTest(context) {
                 storageUrl: plan.storageUrl,
                 sizeBytes: plan.sizeBytes,
                 selectionSource: plan.selectionSource,
-            }));
+            }), runtime);
             return;
         }
         const result = await testStorageUpload(db, {

package/dist/commands/storage/repo/configs.d.ts

@@ -0,0 +1,30 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import { type StorageListResult, type StorageStatsResult, type StorageTestPlan, type StorageUploadCategory, type StorageUploadPlan, type StoredCustomStorageConfig } from './shared.js';
+export declare function getTableColumns(db: AbstractPowerSyncDatabase, tableName: 'c_storage' | 'c_resource'): Promise<Set<string>>;
+export declare function listStoredCustomStorageConfigs(db: AbstractPowerSyncDatabase, userId: string): Promise<StoredCustomStorageConfig[]>;
+export declare function getActiveCustomStorageConfigId(db: AbstractPowerSyncDatabase, userId: string): Promise<string | null>;
+export declare function resolveStorageSelection(args: {
+    configs: StoredCustomStorageConfig[];
+    storageId?: string;
+    activeCustomStorageConfigId: string | null;
+}): {
+    config: StoredCustomStorageConfig;
+    selectionSource: StorageUploadPlan['selectionSource'];
+};
+export declare function buildStorageUploadPlan(args: {
+    config: StoredCustomStorageConfig;
+    selectionSource: StorageUploadPlan['selectionSource'];
+    userId: string;
+    filePath: string;
+    category: StorageUploadCategory;
+    key?: string;
+    sizeBytes: number;
+}): StorageUploadPlan;
+export declare function buildStorageTestPlan(args: {
+    config: StoredCustomStorageConfig;
+    selectionSource: StorageUploadPlan['selectionSource'];
+    userId: string;
+}): StorageTestPlan;
+export declare function parseStorageUploadCategory(value: unknown): StorageUploadCategory;
+export declare function listStorageConfigs(db: AbstractPowerSyncDatabase, userId: string): Promise<StorageListResult>;
+export declare function getStorageStats(db: AbstractPowerSyncDatabase, userId: string): Promise<StorageStatsResult>;