@dinoxx/dinox-cli 1.0.19 → 1.0.21

package/dist/commands/tags/content.js

@@ -0,0 +1,243 @@
+import { canonicalizeTagPath, isTagPathWithinPrefix, renameTagPathWithPrefix, } from './model.js';
+function dedupeTags(values) {
+    const result = [];
+    const seen = new Set();
+    for (const value of values) {
+        const tag = canonicalizeTagPath(value);
+        const key = tag.toLowerCase();
+        if (!tag || seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(tag);
+    }
+    return result;
+}
+function sameArray(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+function rewriteTagList(tags, oldPrefix, newPrefix, preserveSuffix) {
+    return dedupeTags(tags.map((tag) => (isTagPathWithinPrefix(tag, oldPrefix)
+        ? (preserveSuffix ? renameTagPathWithPrefix(tag, oldPrefix, newPrefix) : canonicalizeTagPath(newPrefix))
+        : tag)));
+}
+function pathKey(value) {
+    return canonicalizeTagPath(value).toLowerCase();
+}
+function getPathId(path, lookup) {
+    return lookup?.idByPath.get(pathKey(path)) ?? canonicalizeTagPath(path);
+}
+function parseJson(raw) {
+    if (!raw) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function extractHashtagPath(attrs, lookup) {
+    const label = typeof attrs?.label === 'string' ? canonicalizeTagPath(attrs.label) : '';
+    if (label) {
+        return label;
+    }
+    const id = typeof attrs?.id === 'string' ? attrs.id.trim() : '';
+    if (!id) {
+        return '';
+    }
+    const mapped = lookup?.pathById.get(id);
+    return mapped ? canonicalizeTagPath(mapped) : canonicalizeTagPath(id);
+}
+function rewriteHashtagsInJson(raw, oldPrefix, newPrefix, preserveSuffix, lookup) {
+    const parsed = parseJson(raw);
+    if (!parsed) {
+        return { changed: false, contentJson: raw, plainText: null };
+    }
+    const walk = (node) => {
+        let changed = false;
+        let current = node;
+        if (current.type === 'hashtag') {
+            const attrs = { ...(current.attrs ?? {}) };
+            const path = extractHashtagPath(attrs, lookup);
+            if (path && isTagPathWithinPrefix(path, oldPrefix)) {
+                const nextPath = preserveSuffix
+                    ? renameTagPathWithPrefix(path, oldPrefix, newPrefix)
+                    : canonicalizeTagPath(newPrefix);
+                const nextId = getPathId(nextPath, lookup);
+                if (attrs.label !== nextPath || attrs.id !== nextId) {
+                    current = {
+                        ...current,
+                        attrs: {
+                            ...attrs,
+                            id: nextId,
+                            label: nextPath,
+                        },
+                    };
+                    changed = true;
+                }
+            }
+        }
+        if (Array.isArray(current.content)) {
+            const nextContent = [];
+            let childChanged = false;
+            for (const child of current.content) {
+                const result = walk(child);
+                nextContent.push(result.node);
+                childChanged ||= result.changed;
+            }
+            if (childChanged) {
+                current = { ...current, content: nextContent };
+                changed = true;
+            }
+        }
+        return { changed, node: current };
+    };
+    const result = walk(parsed);
+    if (!result.changed) {
+        return { changed: false, contentJson: raw, plainText: null };
+    }
+    return {
+        changed: true,
+        contentJson: JSON.stringify(result.node),
+        plainText: collectPlainText(result.node, lookup),
+    };
+}
+function collectPlainText(node, lookup) {
+    if (!node) {
+        return null;
+    }
+    const chunks = [];
+    const visit = (current) => {
+        if (current.type === 'hashtag') {
+            const path = extractHashtagPath(current.attrs, lookup);
+            if (path) {
+                chunks.push(`#${path}`);
+            }
+            return;
+        }
+        if (typeof current.text === 'string') {
+            chunks.push(current.text);
+        }
+        if (Array.isArray(current.content)) {
+            for (const child of current.content) {
+                visit(child);
+            }
+            chunks.push('\n');
+        }
+    };
+    visit(node);
+    const text = chunks.join('').trim();
+    return text || null;
+}
+function isSegmentChar(charCode) {
+    return ((charCode >= 0x30 && charCode <= 0x39) ||
+        (charCode >= 0x41 && charCode <= 0x5a) ||
+        (charCode >= 0x61 && charCode <= 0x7a) ||
+        charCode === 0x5f ||
+        charCode === 0x2d ||
+        (charCode >= 0x4e00 && charCode <= 0x9fff));
+}
+function isBoundaryBlockingChar(charCode) {
+    return ((charCode >= 0x30 && charCode <= 0x39) ||
+        (charCode >= 0x41 && charCode <= 0x5a) ||
+        (charCode >= 0x61 && charCode <= 0x7a) ||
+        charCode === 0x5f ||
+        (charCode >= 0x4e00 && charCode <= 0x9fff));
+}
+function parseHashtag(source, hashIndex) {
+    if (hashIndex > 0 && isBoundaryBlockingChar(source.charCodeAt(hashIndex - 1))) {
+        return null;
+    }
+    let index = hashIndex + 1;
+    let sawChar = false;
+    let segmentHasChar = false;
+    while (index < source.length) {
+        const code = source.charCodeAt(index);
+        if (isSegmentChar(code)) {
+            sawChar = true;
+            segmentHasChar = true;
+            index += 1;
+            continue;
+        }
+        if (code === 0x2f) {
+            const nextCode = source.charCodeAt(index + 1);
+            if (!segmentHasChar || !isSegmentChar(nextCode)) {
+                return null;
+            }
+            segmentHasChar = false;
+            index += 1;
+            continue;
+        }
+        break;
+    }
+    if (!sawChar || !segmentHasChar) {
+        return null;
+    }
+    return {
+        raw: source.slice(hashIndex, index),
+        label: source.slice(hashIndex + 1, index),
+        to: index,
+    };
+}
+function rewriteHashtagsInMarkdown(raw, oldPrefix, newPrefix, preserveSuffix) {
+    if (!raw) {
+        return { changed: false, contentMd: raw };
+    }
+    let output = '';
+    let changed = false;
+    for (let index = 0; index < raw.length;) {
+        if (raw.charCodeAt(index) !== 0x23) {
+            output += raw[index];
+            index += 1;
+            continue;
+        }
+        const match = parseHashtag(raw, index);
+        if (!match) {
+            output += raw[index];
+            index += 1;
+            continue;
+        }
+        const path = canonicalizeTagPath(match.label);
+        if (path && isTagPathWithinPrefix(path, oldPrefix)) {
+            const nextPath = preserveSuffix
+                ? renameTagPathWithPrefix(path, oldPrefix, newPrefix)
+                : canonicalizeTagPath(newPrefix);
+            output += `#${nextPath}`;
+            changed = true;
+        }
+        else {
+            output += match.raw;
+        }
+        index = match.to;
+    }
+    return { changed, contentMd: changed ? output : raw };
+}
+export function renameTagReferencesInNote(args) {
+    return rewriteTagReferencesInNote({ ...args, preserveSuffix: true });
+}
+export function mergeTagReferencesInNote(args) {
+    return rewriteTagReferencesInNote({ ...args, preserveSuffix: false });
+}
+function rewriteTagReferencesInNote(args) {
+    const nextTags = rewriteTagList(args.tags, args.oldPrefix, args.newPrefix, args.preserveSuffix);
+    const json = rewriteHashtagsInJson(args.contentJson, args.oldPrefix, args.newPrefix, args.preserveSuffix, args.lookup);
+    const markdown = rewriteHashtagsInMarkdown(args.contentMd, args.oldPrefix, args.newPrefix, args.preserveSuffix);
+    const tagsChanged = !sameArray(nextTags, args.tags);
+    const nextContentText = json.changed ? json.plainText : args.contentText;
+    return {
+        tagsChanged,
+        contentJsonChanged: json.changed,
+        contentMdChanged: markdown.changed,
+        contentTextChanged: json.changed,
+        tags: nextTags,
+        contentJson: json.contentJson,
+        contentMd: markdown.contentMd,
+        contentText: nextContentText,
+    };
+}

package/dist/commands/tags/index.js

@@ -1,49 +1,25 @@
 import { resolveAuthIdentity } from '../../auth/userInfo.js';
-import { loadConfig } from '../../config/store.js';
-import { resolveConfig } from '../../config/resolve.js';
-import { connectPowerSync, waitForIdleDataFlow } from '../../powersync/runtime.js';
-import { syncNoteTokenIndex } from '../../powersync/tokenIndex.js';
 import { registerCommandGroup } from '../descriptor/register.js';
 import { FORMAT_OPTIONS, OFFLINE_OPTIONS, SYNC_TIMEOUT_OPTIONS } from '../schema/globalOptions.js';
-import { buildTagAddDryRunPreview } from '../writeDryRun.js';
+import { buildTagAddDryRunPreview, buildTagMutationDryRunPreview } from '../writeDryRun.js';
 import { printDryRunPreview } from '../../utils/dryRun.js';
 import { DinoxError } from '../../utils/errors.js';
 import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
-import { parseSyncTimeoutMs } from '../../utils/syncTimeout.js';
+import { commandStale, printStaleCacheWarning, printUploadDisabledWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
 import { addTag, inspectAddTag, listTags } from './repo.js';
+import { getTagStats, getTagTree, inspectTagCleanup, mergeTag, moveTag, renameTag, suggestTagMerges, } from './operations.js';
 const TAG_GLOBAL_OPTIONS = [...FORMAT_OPTIONS, ...OFFLINE_OPTIONS, ...SYNC_TIMEOUT_OPTIONS];
-async function syncBeforeTagCommand(db, offline, timeoutMs) {
-    if (offline) {
-        return;
-    }
-    await waitForIdleDataFlow(db, Math.min(timeoutMs, 10_000));
-    await syncNoteTokenIndex(db);
-}
-async function withTagDb(context, run) {
-    const rawConfig = await loadConfig();
-    const config = resolveConfig(rawConfig);
-    const timeoutMs = parseSyncTimeoutMs(context.globals.syncTimeout) ?? config.sync.timeoutMs;
-    const offline = Boolean(context.globals.offline);
-    const { db, stale } = await connectPowerSync({ config, offline, timeoutMs });
-    try {
-        await run({ db, config, rawConfig, offline, timeoutMs, stale });
-    }
-    finally {
-        await db.close().catch(() => undefined);
-    }
-}
 async function runTagList(context) {
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withTagDb(context, async ({ db, offline, timeoutMs, stale }) => {
-        await syncBeforeTagCommand(db, offline, timeoutMs);
-        const tags = await listTags(db);
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        const tags = await listTags(runtime.db, { userId: identity.userId });
         if (structuredOutput) {
-            printSuccess({ stale, count: tags.length, tags });
+            printSuccess({ stale: commandStale(runtime), count: tags.length, tags });
             return;
         }
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; results may be stale');
-        }
+        printStaleCacheWarning(runtime, 'warning: sync timed out; results may be stale');
         if (tags.length === 0) {
             printHumanReadableLine('No tags.');
             return;
@@ -53,6 +29,20 @@ async function runTagList(context) {
         }
     });
 }
+async function runTagTree(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess({ stale: commandStale(runtime), tree: await getTagTree(runtime.db, { userId: identity.userId }) });
+    });
+}
+async function runTagStats(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess({ stale: commandStale(runtime), ...(await getTagStats(runtime.db, { userId: identity.userId })) });
+    });
+}
 async function runTagAdd(context) {
     const nameArg = context.args.name;
     const optionName = typeof context.options.name === 'string' ? context.options.name : undefined;
@@ -64,15 +54,15 @@ async function runTagAdd(context) {
         throw new DinoxError('Conflicting tag name values from positional argument and --name option.');
     }
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
-    await withTagDb(context, async ({ db, config, rawConfig, offline, timeoutMs, stale }) => {
-        const identity = await resolveAuthIdentity(rawConfig, config);
-        await syncBeforeTagCommand(db, offline, timeoutMs);
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
         const emoji = typeof context.options.emoji === 'string' ? context.options.emoji : undefined;
         if (Boolean(context.options.dryRun)) {
             printDryRunPreview(buildTagAddDryRunPreview({
-                config,
-                offline,
-                ...(await inspectAddTag(db, {
+                config: runtime.config,
+                offline: runtime.offline,
+                ...(await inspectAddTag(runtime.db, {
                     name,
                     userId: identity.userId,
                     emoji,
@@ -80,26 +70,137 @@ async function runTagAdd(context) {
             }));
             return;
         }
-        const result = await addTag(db, {
+        const result = await addTag(runtime.db, {
             name,
             userId: identity.userId,
             emoji,
         });
-        if (!offline && !config.powersync.uploadBaseUrl) {
-            printHumanReadableLine('warning: upload disabled (powersync.uploadBaseUrl is unset); changes are local-only for now');
-        }
-        if (!offline) {
-            await waitForIdleDataFlow(db, Math.min(timeoutMs, 5_000));
-        }
-        const payload = { ok: true, stale: offline ? true : stale, ...result };
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        const payload = { ok: true, stale: commandStale(runtime), ...result };
         if (structuredOutput) {
             printSuccess(payload);
             return;
         }
         printHumanReadableLine(result.id);
-        if (stale && !offline) {
-            printHumanReadableLine('warning: sync timed out; results may be stale');
+        printStaleCacheWarning(runtime, 'warning: sync timed out; results may be stale');
+    });
+}
+async function withTagWriteRuntime(context, run) {
+    return withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        return run({ runtime, userId: identity.userId });
+    });
+}
+function requireArg(value, message) {
+    const trimmed = value?.trim() ?? '';
+    if (!trimmed) {
+        throw new DinoxError(message);
+    }
+    return trimmed;
+}
+async function runTagRename(context) {
+    const path = requireArg(context.args.path, 'Tag path is required');
+    const newName = requireArg(context.args.newName, 'New tag name is required');
+    await withTagWriteRuntime(context, async ({ runtime, userId }) => {
+        const result = await renameTag(runtime.db, { path, newName, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildTagMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino tag rename',
+                action: 'rename_tag',
+                risk: 'write',
+                summary: `Rename tag "${result.fromPath}" to "${result.toPath}".`,
+                inputs: { path, new_name: newName },
+                changes: { updated_tags: result.updatedTags, updated_notes: result.updatedNotes },
+            }));
+            return;
+        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runTagMove(context) {
+    const path = requireArg(context.args.path, 'Tag path is required');
+    const to = typeof context.options.to === 'string' ? context.options.to.trim() : '';
+    if (!to) {
+        throw new DinoxError('--to is required');
+    }
+    await withTagWriteRuntime(context, async ({ runtime, userId }) => {
+        const result = await moveTag(runtime.db, { path, to, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildTagMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino tag move',
+                action: 'move_tag',
+                risk: 'write',
+                summary: `Move tag "${result.fromPath}" to "${result.toPath}".`,
+                inputs: { path, to },
+                changes: { updated_tags: result.updatedTags, updated_notes: result.updatedNotes },
+            }));
+            return;
         }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runTagMerge(context) {
+    const from = requireArg(context.args.from, 'Source tag path is required');
+    const to = requireArg(context.args.to, 'Target tag path is required');
+    await withTagWriteRuntime(context, async ({ runtime, userId }) => {
+        const result = await mergeTag(runtime.db, { from, to, userId }, { dryRun: Boolean(context.options.dryRun) });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildTagMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino tag merge',
+                action: 'merge_tag',
+                risk: 'high-risk-write',
+                summary: `Merge tag subtree "${result.fromPath}" into "${result.toPath}".`,
+                inputs: { from, to },
+                changes: {
+                    soft_deleted_tag_ids: result.softDeletedTagIds,
+                    updated_notes: result.updatedNotes,
+                },
+            }));
+            return;
+        }
+        printUploadDisabledWarning(runtime);
+        await waitForMutationUpload(runtime);
+        printSuccess({ ok: true, stale: commandStale(runtime), ...result });
+    });
+}
+async function runTagSuggest(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        printSuccess({ stale: commandStale(runtime), ...(await suggestTagMerges(runtime.db, { userId: identity.userId })) });
+    });
+}
+async function runTagCleanup(context) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime, { syncTokenIndex: true });
+        const result = await inspectTagCleanup(runtime.db, { userId: identity.userId });
+        if (Boolean(context.options.dryRun)) {
+            printDryRunPreview(buildTagMutationDryRunPreview({
+                config: runtime.config,
+                offline: runtime.offline,
+                command: 'dino tag cleanup',
+                action: 'cleanup_tags',
+                risk: 'write',
+                summary: `Inspect tag cleanup candidates (${result.issues.length} issues).`,
+                inputs: {},
+                targets: result.issues,
+            }));
+            return;
+        }
+        printSuccess({ stale: commandStale(runtime), ...result });
     });
 }
 export const tagCommandGroup = {
@@ -123,6 +224,40 @@ export const tagCommandGroup = {
             },
             action: runTagList,
         },
+        {
+            name: 'tree',
+            description: 'Show tags as a hierarchy tree from c_tag_node',
+            schema: {
+                path: 'tag.tree',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Nested tag tree payload',
+                    fields: ['tree.id', 'tree.tag', 'tree.name', 'tree.parentId', 'tree.isActual', 'tree.children', 'stale'],
+                },
+                examples: ['dino tag tree --format json'],
+            },
+            action: runTagTree,
+        },
+        {
+            name: 'stats',
+            description: 'Show tag usage counts and unused-tag status',
+            schema: {
+                path: 'tag.stats',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag statistics payload',
+                    fields: ['totalTags', 'actualTags', 'unusedTags', 'tags.id', 'tags.tag', 'tags.directNoteCount', 'tags.descendantNoteCount', 'tags.latestNoteUpdatedAt', 'tags.isUnused', 'stale'],
+                },
+                examples: ['dino tag stats --format json'],
+            },
+            action: runTagStats,
+        },
         {
             name: 'add',
             description: 'Create a tag path, restoring deleted nodes when possible',
@@ -146,6 +281,107 @@ export const tagCommandGroup = {
             },
             action: runTagAdd,
         },
+        {
+            name: 'rename',
+            description: 'Rename a tag and cascade descendant paths and note references',
+            arguments: [
+                { syntax: '<path>', description: 'Existing tag path' },
+                { syntax: '<new-name>', description: 'New leaf name' },
+            ],
+            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            schema: {
+                path: 'tag.rename',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag rename result',
+                    fields: ['id', 'fromPath', 'toPath', 'updatedTags', 'updatedNotes', 'stale'],
+                },
+                examples: ['dino tag rename "AI/old" "new" --format json --dry-run'],
+            },
+            action: runTagRename,
+        },
+        {
+            name: 'move',
+            description: 'Move a tag under another parent and cascade descendant paths and note references',
+            arguments: [{ syntax: '<path>', description: 'Existing tag path' }],
+            options: [
+                { flags: '--to <parent-path>', description: 'Target parent tag path', required: true, type: 'string' },
+                { flags: '--dry-run', description: 'Preview the write without executing it' },
+            ],
+            schema: {
+                path: 'tag.move',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag move result',
+                    fields: ['id', 'fromPath', 'toPath', 'updatedTags', 'updatedNotes', 'stale'],
+                },
+                examples: ['dino tag move "AI" --to "Technology" --format json --dry-run'],
+            },
+            action: runTagMove,
+        },
+        {
+            name: 'merge',
+            description: 'Merge a tag subtree into another tag and soft-delete the source subtree',
+            arguments: [
+                { syntax: '<from>', description: 'Source tag path' },
+                { syntax: '<to>', description: 'Target tag path' },
+            ],
+            options: [{ flags: '--dry-run', description: 'Preview the write without executing it' }],
+            schema: {
+                path: 'tag.merge',
+                risk: 'high-risk-write',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag merge result',
+                    fields: ['fromId', 'toId', 'fromPath', 'toPath', 'softDeletedTagIds', 'updatedNotes', 'stale'],
+                },
+                examples: ['dino tag merge "ai" "AI" --format json --dry-run'],
+            },
+            action: runTagMerge,
+        },
+        {
+            name: 'suggest',
+            description: 'Suggest likely duplicate tags to merge',
+            schema: {
+                path: 'tag.suggest',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag merge suggestions payload',
+                    fields: ['suggestions.canonical', 'suggestions.variants', 'suggestions.noteCount', 'suggestions.reason', 'stale'],
+                },
+                examples: ['dino tag suggest --format json'],
+            },
+            action: runTagSuggest,
+        },
+        {
+            name: 'cleanup',
+            description: 'Inspect tag cleanup candidates',
+            options: [{ flags: '--dry-run', description: 'Preview cleanup candidates without writing' }],
+            schema: {
+                path: 'tag.cleanup',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: TAG_GLOBAL_OPTIONS,
+                output: {
+                    type: 'structured',
+                    summary: 'Tag cleanup inspection payload',
+                    fields: ['issues', 'nonActualNodes', 'unusedTags', 'duplicatePaths', 'orphanParents', 'deletedWithActiveChildren', 'softDeletedActual', 'stale'],
+                },
+                examples: ['dino tag cleanup --format json --dry-run'],
+            },
+            action: runTagCleanup,
+        },
     ],
 };
 export function registerTagsCommand(program) {

package/dist/commands/tags/model.d.ts

@@ -0,0 +1,38 @@
+export declare const MAX_TAG_SEGMENT_LENGTH = 500;
+export declare const MAX_TAG_PATH_LENGTH = 2000;
+export declare const MAX_TAG_EMOJI_LENGTH = 32;
+export declare const REQUIRED_TAG_NODE_COLUMNS: string[];
+export declare const REQUIRED_NOTE_TAG_COLUMNS: string[];
+export type TableInfoRow = {
+    name: string | null;
+};
+export type MutableTagNode = {
+    id: string;
+    fullPath: string;
+    pathKey: string;
+    parentId: string | null;
+    depth: number | null;
+    isActual: number | null;
+    isDel: number | null;
+    userId: string;
+    emoji: string;
+};
+export type TagListItem = {
+    id: string;
+    tag: string;
+    name: string;
+    parentId: string | null;
+    depth: number | null;
+    emoji: string;
+};
+export declare function trimString(value: string | null | undefined): string;
+export declare function canonicalizeTagPath(value: string): string;
+export declare function normalizeTagLookupKey(value: string): string;
+export declare function getLeafName(path: string): string;
+export declare function parentPathOf(path: string): string | null;
+export declare function isActiveTagNode(node: MutableTagNode): boolean;
+export declare function isActualTagNode(node: MutableTagNode): boolean;
+export declare function isTagPathWithinPrefix(path: string, prefix: string): boolean;
+export declare function renameTagPathWithPrefix(path: string, oldPrefix: string, newPrefix: string): string;
+export declare function assertMaxLength(label: string, value: string, maxLength: number): void;
+export declare function parseStoredTags(raw: string | null): string[];