@dinoxx/dinox-cli 1.1.1 → 2.1.0

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);
+}

package/dist/skills/retired.d.ts

@@ -0,0 +1,60 @@
+import { SKILLS_REPO_SLUG } from '../constants/links.js';
+export type RetiredSkill = Readonly<{
+    name: string;
+    replacement: string | null;
+    replacementNote?: string;
+    source: typeof SKILLS_REPO_SLUG;
+    skillFolderHash: string;
+}>;
+export type RetiredSkillsCleanupGuidance = Readonly<{
+    automaticRemoval: false;
+    inventoryCommand: string;
+    lockFile: string;
+    requiredMatchFields: readonly ['name', 'source', 'skillFolderHash'];
+    guidance: string;
+}>;
+export declare const RETIRED_SKILLS: readonly (Readonly<{
+    name: "create-note";
+    replacement: "dino-note";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "15a91b77e5032e614cbec95997de0f9697cee29c";
+}> | Readonly<{
+    name: "dinox";
+    replacement: "dino-dinox";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "3089a4b076fffd8d6579db26c520f0d97e225a30";
+}> | Readonly<{
+    name: "manage-boxes";
+    replacement: "dino-manage-boxes";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "49ffa648ab341bef20a9ea4696973d39c5c4e1c9";
+}> | Readonly<{
+    name: "manage-tags";
+    replacement: "dino-manage-tags";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "801f6cc91d225503ad67054f66ac024cb12d01cb";
+}> | Readonly<{
+    name: "search-notes";
+    replacement: "dino-note";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "88d3a95a3cb663b555e79be57d2135c0edbe8e0d";
+}> | Readonly<{
+    name: "view-note";
+    replacement: "dino-note";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "639ce5941e19d4f5ffc3a4b5870486e741ab2937";
+}> | Readonly<{
+    name: "dino-shared";
+    replacement: null;
+    replacementNote: "Runtime guidance is embedded in every current Dinox skill.";
+    source: "ryzencool/dinox-cli-skills";
+    skillFolderHash: "842fe8fd30020bf1b58718dcd438d78b4c7d8f33";
+}>)[];
+export declare const RETIRED_SKILLS_CLEANUP: Readonly<{
+    automaticRemoval: false;
+    inventoryCommand: string;
+    lockFile: string;
+    requiredMatchFields: readonly ["name", "source", "skillFolderHash"];
+    guidance: string;
+}>;
+export declare function formatRetiredSkillsSummary(): string;

package/dist/skills/retired.js

@@ -0,0 +1,58 @@
+import { SKILLS_INSTALLER_NAME, SKILLS_INSTALLER_VERSION, SKILLS_REPO_SLUG, } from '../constants/links.js';
+export const RETIRED_SKILLS = Object.freeze([
+    Object.freeze({
+        name: 'create-note',
+        replacement: 'dino-note',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '15a91b77e5032e614cbec95997de0f9697cee29c',
+    }),
+    Object.freeze({
+        name: 'dinox',
+        replacement: 'dino-dinox',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '3089a4b076fffd8d6579db26c520f0d97e225a30',
+    }),
+    Object.freeze({
+        name: 'manage-boxes',
+        replacement: 'dino-manage-boxes',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '49ffa648ab341bef20a9ea4696973d39c5c4e1c9',
+    }),
+    Object.freeze({
+        name: 'manage-tags',
+        replacement: 'dino-manage-tags',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '801f6cc91d225503ad67054f66ac024cb12d01cb',
+    }),
+    Object.freeze({
+        name: 'search-notes',
+        replacement: 'dino-note',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '88d3a95a3cb663b555e79be57d2135c0edbe8e0d',
+    }),
+    Object.freeze({
+        name: 'view-note',
+        replacement: 'dino-note',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '639ce5941e19d4f5ffc3a4b5870486e741ab2937',
+    }),
+    Object.freeze({
+        name: 'dino-shared',
+        replacement: null,
+        replacementNote: 'Runtime guidance is embedded in every current Dinox skill.',
+        source: SKILLS_REPO_SLUG,
+        skillFolderHash: '842fe8fd30020bf1b58718dcd438d78b4c7d8f33',
+    }),
+]);
+export const RETIRED_SKILLS_CLEANUP = Object.freeze({
+    automaticRemoval: false,
+    inventoryCommand: `npx --yes ${SKILLS_INSTALLER_NAME}@${SKILLS_INSTALLER_VERSION} list -g --json`,
+    lockFile: '~/.agents/.skill-lock.json',
+    requiredMatchFields: Object.freeze(['name', 'source', 'skillFolderHash']),
+    guidance: 'Use the inventory command to find candidates, then inspect the installer lock. Remove an installed skill only when its name, source, and skillFolderHash all match this official retired inventory. Never delete a skill directory or lock entry by name alone because unrelated skills can share an ID.',
+});
+export function formatRetiredSkillsSummary() {
+    return RETIRED_SKILLS.map((skill) => (skill.replacement
+        ? `${skill.name} -> ${skill.replacement}`
+        : `${skill.name} -> no direct replacement (${skill.replacementNote})`)).join('; ');
+}

package/dist/utils/deadline.d.ts

@@ -0,0 +1,8 @@
+export type DeadlineOptions = {
+    deadlineAtMs?: number;
+    maximumTimeoutMs: number;
+    createTimeoutError: () => Error;
+    runWhenExpired?: boolean;
+};
+export declare function remainingDeadlineMs(deadlineAtMs: number | undefined, maximumTimeoutMs: number, now?: () => number): number;
+export declare function runWithinDeadline<T>(run: () => Promise<T>, options: DeadlineOptions): Promise<T>;

package/dist/utils/deadline.js

@@ -0,0 +1,31 @@
+export function remainingDeadlineMs(deadlineAtMs, maximumTimeoutMs, now = Date.now) {
+    const maximum = Number.isFinite(maximumTimeoutMs)
+        ? Math.max(0, Math.floor(maximumTimeoutMs))
+        : 0;
+    if (deadlineAtMs === undefined) {
+        return maximum;
+    }
+    return Math.max(0, Math.min(maximum, Math.floor(deadlineAtMs - now())));
+}
+export async function runWithinDeadline(run, options) {
+    if (options.deadlineAtMs === undefined) {
+        return run();
+    }
+    const remainingMs = remainingDeadlineMs(options.deadlineAtMs, options.maximumTimeoutMs);
+    if (remainingMs <= 0 && !options.runWhenExpired) {
+        throw options.createTimeoutError();
+    }
+    const operation = Promise.resolve().then(run);
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(options.createTimeoutError()), Math.max(1, remainingMs));
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/utils/dryRun.d.ts

@@ -8,6 +8,25 @@ export type DryRunPreview = {
     inputs?: Record<string, unknown>;
     targets?: Array<Record<string, unknown>>;
     changes?: Record<string, unknown> | Array<Record<string, unknown>>;
+    stale?: boolean;
+    sync?: {
+        offline: boolean;
+        gate: {
+            ok: boolean;
+            reasons: string[];
+        } | null;
+    };
 };
+export type DryRunExecutionState = {
+    offline: boolean;
+    stale: boolean;
+    sync?: {
+        gate?: {
+            ok: boolean;
+            reasons: string[];
+        } | null;
+    };
+};
+export declare function attachDryRunExecutionState(preview: DryRunPreview, state: DryRunExecutionState): DryRunPreview;
 export declare function formatDryRunPreview(preview: DryRunPreview): string;
-export declare function printDryRunPreview(preview: DryRunPreview): void;
+export declare function printDryRunPreview(preview: DryRunPreview, state?: DryRunExecutionState): void;

package/dist/utils/dryRun.js

@@ -1,4 +1,14 @@
 import { getRequestedStructuredOutputFormat, printHumanReadableBlock, printSuccess, } from './output.js';
+export function attachDryRunExecutionState(preview, state) {
+    return {
+        ...preview,
+        stale: state.offline || state.stale,
+        sync: {
+            offline: state.offline,
+            gate: state.sync?.gate ?? null,
+        },
+    };
+}
 function formatValue(value) {
     if (value === null || value === undefined) {
         return String(value);
@@ -36,6 +46,14 @@ export function formatDryRunPreview(preview) {
         `Risk: ${preview.risk}`,
         `Summary: ${preview.summary}`,
     ];
+    if (typeof preview.stale === 'boolean') {
+        lines.push(`Freshness: ${preview.stale ? 'stale' : 'fresh'}`);
+    }
+    if (preview.sync) {
+        const gate = preview.sync.gate;
+        const gateSummary = gate ? (gate.ok ? 'ok' : `blocked (${gate.reasons.join(', ')})`) : 'not evaluated';
+        lines.push(`Sync: ${preview.sync.offline ? 'offline' : 'online'}; gate ${gateSummary}`);
+    }
     if (preview.warnings && preview.warnings.length > 0) {
         lines.push('');
         lines.push('Warnings:');
@@ -60,10 +78,11 @@ export function formatDryRunPreview(preview) {
     }
     return `${lines.join('\n')}\n`;
 }
-export function printDryRunPreview(preview) {
+export function printDryRunPreview(preview, state) {
+    const output = state ? attachDryRunExecutionState(preview, state) : preview;
     if (getRequestedStructuredOutputFormat()) {
-        printSuccess(preview);
+        printSuccess(output);
         return;
     }
-    printHumanReadableBlock(formatDryRunPreview(preview));
+    printHumanReadableBlock(formatDryRunPreview(output));
 }