@dinoxx/dinox-cli 1.0.20 → 1.0.21

package/dist/commands/tags/model.js

@@ -0,0 +1,100 @@
+import { DinoxError } from '../../utils/errors.js';
+export const MAX_TAG_SEGMENT_LENGTH = 500;
+export const MAX_TAG_PATH_LENGTH = 2000;
+export const MAX_TAG_EMOJI_LENGTH = 32;
+export const REQUIRED_TAG_NODE_COLUMNS = [
+    'id',
+    'user_id',
+    'emoji',
+    'full_path',
+    'path_key',
+    'parent_id',
+    'depth',
+    'is_actual',
+    'is_del',
+    'created_at',
+    'updated_at',
+    'meta',
+];
+export const REQUIRED_NOTE_TAG_COLUMNS = [
+    'id',
+    'tags',
+    'content_json',
+    'content_md',
+    'content_text',
+    'updated_at',
+    'version',
+    'is_del',
+    'user_no',
+];
+export function trimString(value) {
+    return value?.trim() ?? '';
+}
+export function canonicalizeTagPath(value) {
+    return value
+        .split(/[\\/]+/g)
+        .map((segment) => segment.trim())
+        .filter(Boolean)
+        .join('/');
+}
+export function normalizeTagLookupKey(value) {
+    return canonicalizeTagPath(value).toLowerCase();
+}
+export function getLeafName(path) {
+    return path.split('/').at(-1) ?? path;
+}
+export function parentPathOf(path) {
+    const segments = path.split('/');
+    if (segments.length <= 1) {
+        return null;
+    }
+    return segments.slice(0, -1).join('/');
+}
+export function isActiveTagNode(node) {
+    return node.isDel === null || node.isDel === 0;
+}
+export function isActualTagNode(node) {
+    return node.isActual === null || node.isActual !== 0;
+}
+export function isTagPathWithinPrefix(path, prefix) {
+    const pathKey = normalizeTagLookupKey(path);
+    const prefixKey = normalizeTagLookupKey(prefix);
+    return pathKey === prefixKey || pathKey.startsWith(`${prefixKey}/`);
+}
+export function renameTagPathWithPrefix(path, oldPrefix, newPrefix) {
+    const oldSegments = canonicalizeTagPath(oldPrefix).split('/');
+    const pathSegments = canonicalizeTagPath(path).split('/');
+    const suffix = pathSegments.slice(oldSegments.length).join('/');
+    return suffix ? `${canonicalizeTagPath(newPrefix)}/${suffix}` : canonicalizeTagPath(newPrefix);
+}
+export function assertMaxLength(label, value, maxLength) {
+    if (value.length > maxLength) {
+        throw new DinoxError(`${label} must be at most ${maxLength} characters`);
+    }
+}
+export function parseStoredTags(raw) {
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        const result = [];
+        const seen = new Set();
+        for (const value of parsed) {
+            const normalized = canonicalizeTagPath(String(value));
+            const key = normalizeTagLookupKey(normalized);
+            if (!key || seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            result.push(normalized);
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

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

@@ -0,0 +1,105 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { TagListItem } from './model.js';
+export type TagTreeNode = TagListItem & {
+    isActual: boolean;
+    children: TagTreeNode[];
+};
+export type TagStatsItem = TagListItem & {
+    isActual: boolean;
+    directNoteCount: number;
+    descendantNoteCount: number;
+    latestNoteUpdatedAt: string | null;
+    isUnused: boolean;
+};
+export type TagStatsResult = {
+    totalTags: number;
+    actualTags: number;
+    unusedTags: number;
+    tags: TagStatsItem[];
+};
+export type TagCleanupIssue = {
+    type: 'non_actual_node' | 'unused_tag' | 'duplicate_path' | 'orphan_parent' | 'deleted_with_active_children' | 'soft_deleted_actual';
+    id: string;
+    path: string;
+    name: string;
+    parentId: string | null;
+    detail: string;
+    duplicateIds?: string[];
+    childIds?: string[];
+};
+export type TagCleanupResult = {
+    issues: TagCleanupIssue[];
+    nonActualNodes: number;
+    unusedTags: number;
+    duplicatePaths: number;
+    orphanParents: number;
+    deletedWithActiveChildren: number;
+    softDeletedActual: number;
+};
+export type TagSubtreeChange = {
+    id: string;
+    fromPath: string;
+    toPath: string;
+};
+export type TagRenameMoveResult = {
+    id: string;
+    fromPath: string;
+    toPath: string;
+    updatedTags: TagSubtreeChange[];
+    updatedNotes: Array<{
+        id: string;
+        before: string[];
+        after: string[];
+    }>;
+};
+export type TagMergeResult = {
+    fromId: string;
+    toId: string;
+    fromPath: string;
+    toPath: string;
+    softDeletedTagIds: string[];
+    updatedNotes: Array<{
+        id: string;
+        before: string[];
+        after: string[];
+    }>;
+};
+export type TagSuggestResult = {
+    suggestions: Array<{
+        canonical: string;
+        variants: string[];
+        noteCount: number;
+        reason: string;
+    }>;
+};
+export type TagReadInput = {
+    userId?: string;
+};
+export type TagRenameInput = {
+    path: string;
+    newName: string;
+    userId: string;
+};
+export type TagMoveInput = {
+    path: string;
+    to: string;
+    userId: string;
+};
+export type TagMergeInput = {
+    from: string;
+    to: string;
+    userId: string;
+};
+export declare function getTagTree(db: AbstractPowerSyncDatabase, input?: TagReadInput): Promise<TagTreeNode[]>;
+export declare function getTagStats(db: AbstractPowerSyncDatabase, input?: TagReadInput): Promise<TagStatsResult>;
+export declare function renameTag(db: AbstractPowerSyncDatabase, input: TagRenameInput, options?: {
+    dryRun?: boolean;
+}): Promise<TagRenameMoveResult>;
+export declare function moveTag(db: AbstractPowerSyncDatabase, input: TagMoveInput, options?: {
+    dryRun?: boolean;
+}): Promise<TagRenameMoveResult>;
+export declare function mergeTag(db: AbstractPowerSyncDatabase, input: TagMergeInput, options?: {
+    dryRun?: boolean;
+}): Promise<TagMergeResult>;
+export declare function inspectTagCleanup(db: AbstractPowerSyncDatabase, input?: TagReadInput): Promise<TagCleanupResult>;
+export declare function suggestTagMerges(db: AbstractPowerSyncDatabase, input?: TagReadInput): Promise<TagSuggestResult>;

package/dist/commands/tags/operations.js

@@ -0,0 +1,438 @@
+import { withPowerSyncWriteTransaction } from '../../powersync/runtime.js';
+import { DinoxError } from '../../utils/errors.js';
+import { nowIsoUtc } from '../../utils/time.js';
+import { mergeTagReferencesInNote, renameTagReferencesInNote } from './content.js';
+import { MAX_TAG_PATH_LENGTH, MAX_TAG_SEGMENT_LENGTH, REQUIRED_NOTE_TAG_COLUMNS, REQUIRED_TAG_NODE_COLUMNS, assertMaxLength, canonicalizeTagPath, getLeafName, isActiveTagNode, isActualTagNode, isTagPathWithinPrefix, normalizeTagLookupKey, parseStoredTags, parentPathOf, renameTagPathWithPrefix, trimString, } from './model.js';
+import { activeTagNodes, actualActiveTagNodes, assertCanWriteTag, assertRequiredColumns, assertWritableTagNodes, descendantsOf, ensureNoTagPathConflict, getTableColumns, loadTagNodes, parentIdForPath, requireActiveTagPath, toTagListItem, } from './store.js';
+function parseSingleSegment(value, label) {
+    const normalized = canonicalizeTagPath(value);
+    if (!normalized || normalized.includes('/')) {
+        throw new DinoxError(`${label} must be a single path segment`);
+    }
+    assertMaxLength(label, normalized, MAX_TAG_SEGMENT_LENGTH);
+    return normalized;
+}
+function assertPath(value, label) {
+    const normalized = canonicalizeTagPath(value);
+    if (!normalized) {
+        throw new DinoxError(`${label} is required`);
+    }
+    assertMaxLength(label, normalized, MAX_TAG_PATH_LENGTH);
+    return normalized;
+}
+function buildSubtreeChanges(nodes, root, newRootPath) {
+    const targetPath = assertPath(newRootPath, 'Target tag path');
+    return descendantsOf(nodes, root).map((node) => ({
+        id: node.id,
+        fromPath: node.fullPath,
+        toPath: renameTagPathWithPrefix(node.fullPath, root.fullPath, targetPath),
+    }));
+}
+function toTreeNode(node) {
+    return {
+        ...toTagListItem(node),
+        isActual: isActualTagNode(node),
+        children: [],
+    };
+}
+export async function getTagTree(db, input = {}) {
+    const columns = await getTableColumns(db, 'c_tag_node');
+    assertRequiredColumns('c_tag_node', columns, REQUIRED_TAG_NODE_COLUMNS);
+    const nodes = activeTagNodes(await loadTagNodes(db, columns, { userId: input.userId, dedupeByPath: true }));
+    const byId = new Map(nodes.map((node) => [node.id, toTreeNode(node)]));
+    const roots = [];
+    for (const node of nodes) {
+        const treeNode = byId.get(node.id);
+        const parent = node.parentId ? byId.get(node.parentId) : null;
+        if (parent) {
+            parent.children.push(treeNode);
+        }
+        else {
+            roots.push(treeNode);
+        }
+    }
+    const sortTree = (items) => {
+        items.sort((left, right) => left.tag.localeCompare(right.tag));
+        for (const item of items) {
+            sortTree(item.children);
+        }
+    };
+    sortTree(roots);
+    return roots;
+}
+async function loadNoteTagRows(db, userId) {
+    return db.getAll(`
+    SELECT
+      TRIM(COALESCE(id, '')) AS id,
+      title,
+      tags,
+      content_json,
+      content_md,
+      content_text,
+      is_del,
+      TRIM(COALESCE(user_no, '')) AS user_no,
+      updated_at
+    FROM c_note
+    WHERE TRIM(COALESCE(id, '')) <> ''
+      AND (is_del IS NULL OR is_del = 0)
+      AND (TRIM(COALESCE(user_no, '')) = ? OR TRIM(COALESCE(user_no, '')) = '')
+    `, [userId]);
+}
+async function loadNoteTagStats(db, userId) {
+    const normalizedUserId = trimString(userId);
+    const userFilter = normalizedUserId
+        ? `AND (TRIM(COALESCE(n.user_no, '')) = ? OR TRIM(COALESCE(n.user_no, '')) = '')`
+        : '';
+    const rows = await db.getAll(`
+    SELECT
+      TRIM(CAST(tag_item.value AS TEXT)) AS tag,
+      COUNT(DISTINCT n.id) AS note_count,
+      MAX(COALESCE(n.updated_at, n.created_at)) AS latest_note_updated_at
+    FROM c_note n,
+      json_each(
+        CASE
+          WHEN json_valid(COALESCE(n.tags, '')) THEN n.tags
+          ELSE '[]'
+        END
+      ) tag_item
+    WHERE (n.is_del IS NULL OR n.is_del = 0)
+      ${userFilter}
+      AND TRIM(CAST(tag_item.value AS TEXT)) <> ''
+    GROUP BY TRIM(CAST(tag_item.value AS TEXT))
+    `, normalizedUserId ? [normalizedUserId] : []);
+    const stats = new Map();
+    for (const row of rows) {
+        const key = normalizeTagLookupKey(row.tag ?? '');
+        if (!key) {
+            continue;
+        }
+        stats.set(key, {
+            directNoteCount: Number(row.note_count ?? 0),
+            latestNoteUpdatedAt: row.latest_note_updated_at ?? null,
+        });
+    }
+    return stats;
+}
+export async function getTagStats(db, input = {}) {
+    const columns = await getTableColumns(db, 'c_tag_node');
+    assertRequiredColumns('c_tag_node', columns, REQUIRED_TAG_NODE_COLUMNS);
+    const nodes = activeTagNodes(await loadTagNodes(db, columns, { userId: input.userId, dedupeByPath: true }));
+    const statsByPath = await loadNoteTagStats(db, input.userId);
+    const tags = nodes.map((node) => {
+        let descendantNoteCount = 0;
+        let latestNoteUpdatedAt = null;
+        for (const descendant of descendantsOf(nodes, node)) {
+            const stats = statsByPath.get(normalizeTagLookupKey(descendant.fullPath));
+            descendantNoteCount += stats?.directNoteCount ?? 0;
+            if (stats?.latestNoteUpdatedAt && (!latestNoteUpdatedAt || stats.latestNoteUpdatedAt > latestNoteUpdatedAt)) {
+                latestNoteUpdatedAt = stats.latestNoteUpdatedAt;
+            }
+        }
+        const direct = statsByPath.get(normalizeTagLookupKey(node.fullPath));
+        return {
+            ...toTagListItem(node),
+            isActual: isActualTagNode(node),
+            directNoteCount: direct?.directNoteCount ?? 0,
+            descendantNoteCount,
+            latestNoteUpdatedAt,
+            isUnused: isActualTagNode(node) && descendantNoteCount === 0,
+        };
+    });
+    tags.sort((left, right) => left.tag.localeCompare(right.tag));
+    return {
+        totalTags: tags.length,
+        actualTags: tags.filter((tag) => tag.isActual).length,
+        unusedTags: tags.filter((tag) => tag.isUnused).length,
+        tags,
+    };
+}
+function buildTagReferenceLookup(nodes, changes = [], aliases = []) {
+    const idByPath = new Map();
+    const pathById = new Map();
+    for (const node of activeTagNodes(nodes)) {
+        const path = canonicalizeTagPath(node.fullPath);
+        if (!path) {
+            continue;
+        }
+        idByPath.set(normalizeTagLookupKey(path), node.id);
+        pathById.set(node.id, path);
+    }
+    for (const change of changes) {
+        const path = canonicalizeTagPath(change.toPath);
+        if (!path) {
+            continue;
+        }
+        idByPath.set(normalizeTagLookupKey(path), change.id);
+    }
+    for (const alias of aliases) {
+        const path = canonicalizeTagPath(alias.path);
+        if (!path || !alias.id) {
+            continue;
+        }
+        idByPath.set(normalizeTagLookupKey(path), alias.id);
+    }
+    return { idByPath, pathById };
+}
+function updateNoteTagsForPrefix(row, oldPrefix, newPrefix, mode, lookup) {
+    const before = parseStoredTags(row.tags);
+    const rewrite = mode === 'merge' ? mergeTagReferencesInNote : renameTagReferencesInNote;
+    const update = rewrite({
+        tags: before,
+        contentJson: row.content_json,
+        contentMd: row.content_md,
+        contentText: row.content_text,
+        oldPrefix,
+        newPrefix,
+        lookup,
+    });
+    return {
+        id: trimString(row.id),
+        before,
+        after: update.tags,
+        contentJson: update.contentJson,
+        contentMd: update.contentMd,
+        contentText: update.contentText,
+        changed: update.tagsChanged || update.contentJsonChanged || update.contentMdChanged,
+    };
+}
+async function applyNoteUpdates(tx, updates, timestamp) {
+    for (const update of updates.filter((item) => item.id && item.changed)) {
+        await tx.execute(`
+      UPDATE c_note
+      SET tags = ?, content_json = ?, content_md = ?, content_text = ?, updated_at = ?, version = COALESCE(version, 0) + 1
+      WHERE id = ?
+      `, [
+            JSON.stringify(update.after),
+            update.contentJson,
+            update.contentMd,
+            update.contentText,
+            timestamp,
+            update.id,
+        ]);
+    }
+}
+async function applyTagPathChanges(tx, nodes, changes, timestamp) {
+    for (const change of changes) {
+        const parentId = parentIdForPath(change.toPath, nodes, changes);
+        const depth = change.toPath.split('/').filter(Boolean).length - 1;
+        await tx.execute(`
+      UPDATE c_tag_node
+      SET full_path = ?, path_key = ?, parent_id = ?, depth = ?, updated_at = ?
+      WHERE id = ?
+      `, [change.toPath, change.toPath, parentId, depth, timestamp, change.id]);
+    }
+}
+export async function renameTag(db, input, options = {}) {
+    const path = assertPath(input.path, 'Tag path');
+    const newName = parseSingleSegment(input.newName, 'New tag name');
+    const userId = trimString(input.userId);
+    const tagColumns = await getTableColumns(db, 'c_tag_node');
+    const noteColumns = await getTableColumns(db, 'c_note');
+    assertCanWriteTag(tagColumns, userId, 'update');
+    assertRequiredColumns('c_note', noteColumns, REQUIRED_NOTE_TAG_COLUMNS);
+    const nodes = await loadTagNodes(db, tagColumns, { userId, dedupeByPath: true });
+    const root = requireActiveTagPath(nodes, path, 'Tag path');
+    const newRootPath = parentPathOf(root.fullPath) ? `${parentPathOf(root.fullPath)}/${newName}` : newName;
+    const changes = buildSubtreeChanges(nodes, root, newRootPath);
+    ensureNoTagPathConflict(nodes, changes);
+    assertWritableTagNodes(nodes, new Set(changes.map((change) => change.id)), userId);
+    const lookup = buildTagReferenceLookup(nodes, changes);
+    const noteUpdates = (await loadNoteTagRows(db, userId))
+        .map((row) => updateNoteTagsForPrefix(row, root.fullPath, newRootPath, 'rename', lookup))
+        .filter((row) => row.id && row.changed);
+    if (!options.dryRun) {
+        await withPowerSyncWriteTransaction(db, async (tx) => {
+            const timestamp = nowIsoUtc();
+            await applyTagPathChanges(tx, nodes, changes, timestamp);
+            await applyNoteUpdates(tx, noteUpdates, timestamp);
+        });
+    }
+    return {
+        id: root.id,
+        fromPath: root.fullPath,
+        toPath: newRootPath,
+        updatedTags: changes,
+        updatedNotes: noteUpdates.map(({ id, before, after }) => ({ id, before, after })),
+    };
+}
+export async function moveTag(db, input, options = {}) {
+    const path = assertPath(input.path, 'Tag path');
+    const to = assertPath(input.to, 'Target parent path');
+    const userId = trimString(input.userId);
+    const tagColumns = await getTableColumns(db, 'c_tag_node');
+    const noteColumns = await getTableColumns(db, 'c_note');
+    assertCanWriteTag(tagColumns, userId, 'update');
+    assertRequiredColumns('c_note', noteColumns, REQUIRED_NOTE_TAG_COLUMNS);
+    const nodes = await loadTagNodes(db, tagColumns, { userId, dedupeByPath: true });
+    const root = requireActiveTagPath(nodes, path, 'Tag path');
+    const parent = requireActiveTagPath(nodes, to, 'Target parent path');
+    if (root.id === parent.id || isTagPathWithinPrefix(parent.fullPath, root.fullPath)) {
+        throw new DinoxError('Cannot move a tag under itself or one of its descendants');
+    }
+    const newRootPath = `${parent.fullPath}/${getLeafName(root.fullPath)}`;
+    const changes = buildSubtreeChanges(nodes, root, newRootPath);
+    ensureNoTagPathConflict(nodes, changes);
+    assertWritableTagNodes(nodes, new Set(changes.map((change) => change.id)), userId);
+    const lookup = buildTagReferenceLookup(nodes, changes);
+    const noteUpdates = (await loadNoteTagRows(db, userId))
+        .map((row) => updateNoteTagsForPrefix(row, root.fullPath, newRootPath, 'rename', lookup))
+        .filter((row) => row.id && row.changed);
+    if (!options.dryRun) {
+        await withPowerSyncWriteTransaction(db, async (tx) => {
+            const timestamp = nowIsoUtc();
+            await applyTagPathChanges(tx, nodes, changes, timestamp);
+            await applyNoteUpdates(tx, noteUpdates, timestamp);
+        });
+    }
+    return {
+        id: root.id,
+        fromPath: root.fullPath,
+        toPath: newRootPath,
+        updatedTags: changes,
+        updatedNotes: noteUpdates.map(({ id, before, after }) => ({ id, before, after })),
+    };
+}
+export async function mergeTag(db, input, options = {}) {
+    const from = assertPath(input.from, 'Source tag path');
+    const to = assertPath(input.to, 'Target tag path');
+    const userId = trimString(input.userId);
+    const tagColumns = await getTableColumns(db, 'c_tag_node');
+    const noteColumns = await getTableColumns(db, 'c_note');
+    assertCanWriteTag(tagColumns, userId, 'update');
+    assertRequiredColumns('c_note', noteColumns, REQUIRED_NOTE_TAG_COLUMNS);
+    const nodes = await loadTagNodes(db, tagColumns, { userId, dedupeByPath: true });
+    const source = requireActiveTagPath(nodes, from, 'Source tag path');
+    const target = requireActiveTagPath(nodes, to, 'Target tag path');
+    if (source.id === target.id || isTagPathWithinPrefix(target.fullPath, source.fullPath)) {
+        throw new DinoxError('Cannot merge a tag into itself or one of its descendants');
+    }
+    const sourceNodes = descendantsOf(nodes, source);
+    assertWritableTagNodes(nodes, new Set([...sourceNodes.map((node) => node.id), target.id]), userId);
+    const lookup = buildTagReferenceLookup(nodes, [], sourceNodes.map((node) => ({ path: node.fullPath, id: target.id })));
+    const noteUpdates = (await loadNoteTagRows(db, userId))
+        .map((row) => updateNoteTagsForPrefix(row, source.fullPath, target.fullPath, 'merge', lookup))
+        .filter((row) => row.id && row.changed);
+    const softDeletedTagIds = sourceNodes.map((node) => node.id);
+    if (!options.dryRun) {
+        await withPowerSyncWriteTransaction(db, async (tx) => {
+            const timestamp = nowIsoUtc();
+            await applyNoteUpdates(tx, noteUpdates, timestamp);
+            for (const tagId of softDeletedTagIds) {
+                await tx.execute(`
+          UPDATE c_tag_node
+          SET is_del = 1, updated_at = ?
+          WHERE id = ?
+          `, [timestamp, tagId]);
+            }
+        });
+    }
+    return {
+        fromId: source.id,
+        toId: target.id,
+        fromPath: source.fullPath,
+        toPath: target.fullPath,
+        softDeletedTagIds,
+        updatedNotes: noteUpdates.map(({ id, before, after }) => ({ id, before, after })),
+    };
+}
+export async function inspectTagCleanup(db, input = {}) {
+    const columns = await getTableColumns(db, 'c_tag_node');
+    assertRequiredColumns('c_tag_node', columns, REQUIRED_TAG_NODE_COLUMNS);
+    const nodes = await loadTagNodes(db, columns, { userId: input.userId });
+    const active = activeTagNodes(nodes);
+    const activeIds = new Set(active.map((node) => node.id));
+    const stats = await getTagStats(db, input);
+    const statsById = new Map(stats.tags.map((tag) => [tag.id, tag]));
+    const issues = [];
+    for (const node of active) {
+        const item = toTagListItem(node);
+        if (!isActualTagNode(node)) {
+            issues.push({ type: 'non_actual_node', id: node.id, path: node.fullPath, name: item.name, parentId: node.parentId, detail: 'Node is a non-actual hierarchy grouping node.' });
+        }
+        if (node.parentId && !activeIds.has(node.parentId)) {
+            issues.push({ type: 'orphan_parent', id: node.id, path: node.fullPath, name: item.name, parentId: node.parentId, detail: `Parent tag is missing or deleted: ${node.parentId}` });
+        }
+        if (statsById.get(node.id)?.isUnused) {
+            issues.push({ type: 'unused_tag', id: node.id, path: node.fullPath, name: item.name, parentId: node.parentId, detail: 'Actual tag has no notes in itself or descendants.' });
+        }
+    }
+    const byPath = new Map();
+    for (const node of active) {
+        const key = normalizeTagLookupKey(node.fullPath);
+        byPath.set(key, [...(byPath.get(key) ?? []), node]);
+    }
+    for (const duplicates of byPath.values()) {
+        if (duplicates.length <= 1) {
+            continue;
+        }
+        for (const node of duplicates) {
+            issues.push({
+                type: 'duplicate_path',
+                id: node.id,
+                path: node.fullPath,
+                name: getLeafName(node.fullPath),
+                parentId: node.parentId,
+                duplicateIds: duplicates.map((item) => item.id),
+                detail: `Active duplicate path appears ${duplicates.length} times.`,
+            });
+        }
+    }
+    for (const node of nodes.filter((item) => !isActiveTagNode(item) && isActualTagNode(item))) {
+        issues.push({ type: 'soft_deleted_actual', id: node.id, path: node.fullPath, name: getLeafName(node.fullPath), parentId: node.parentId, detail: 'Soft-deleted row is still marked as actual.' });
+    }
+    for (const deletedParent of nodes.filter((node) => !isActiveTagNode(node))) {
+        const children = active.filter((child) => child.parentId === deletedParent.id);
+        if (children.length > 0) {
+            issues.push({
+                type: 'deleted_with_active_children',
+                id: deletedParent.id,
+                path: deletedParent.fullPath,
+                name: getLeafName(deletedParent.fullPath),
+                parentId: deletedParent.parentId,
+                childIds: children.map((child) => child.id),
+                detail: 'Deleted tag still has active children.',
+            });
+        }
+    }
+    issues.sort((left, right) => `${left.type}:${left.path}:${left.id}`.localeCompare(`${right.type}:${right.path}:${right.id}`));
+    return {
+        issues,
+        nonActualNodes: issues.filter((issue) => issue.type === 'non_actual_node').length,
+        unusedTags: issues.filter((issue) => issue.type === 'unused_tag').length,
+        duplicatePaths: issues.filter((issue) => issue.type === 'duplicate_path').length,
+        orphanParents: issues.filter((issue) => issue.type === 'orphan_parent').length,
+        deletedWithActiveChildren: issues.filter((issue) => issue.type === 'deleted_with_active_children').length,
+        softDeletedActual: issues.filter((issue) => issue.type === 'soft_deleted_actual').length,
+    };
+}
+function normalizeSuggestionKey(tag) {
+    return canonicalizeTagPath(tag)
+        .toLowerCase()
+        .replace(/[\s_-]+/g, '')
+        .replace(/^人工智能$/u, 'ai')
+        .replace(/^aigc$/u, 'ai');
+}
+export async function suggestTagMerges(db, input = {}) {
+    const columns = await getTableColumns(db, 'c_tag_node');
+    assertRequiredColumns('c_tag_node', columns, REQUIRED_TAG_NODE_COLUMNS);
+    const nodes = actualActiveTagNodes(await loadTagNodes(db, columns, { userId: input.userId, dedupeByPath: true }));
+    const stats = await getTagStats(db, input);
+    const counts = new Map(stats.tags.map((tag) => [normalizeTagLookupKey(tag.tag), tag.directNoteCount]));
+    const groups = new Map();
+    for (const node of nodes) {
+        const key = normalizeSuggestionKey(node.fullPath);
+        groups.set(key, [...(groups.get(key) ?? []), node.fullPath]);
+    }
+    const suggestions = Array.from(groups.values())
+        .filter((variants) => variants.length > 1)
+        .map((variants) => {
+        variants.sort((left, right) => (counts.get(normalizeTagLookupKey(right)) ?? 0) - (counts.get(normalizeTagLookupKey(left)) ?? 0));
+        return {
+            canonical: variants[0],
+            variants,
+            noteCount: variants.reduce((sum, tag) => sum + (counts.get(normalizeTagLookupKey(tag)) ?? 0), 0),
+            reason: 'Tags normalize to the same lowercase/spacing semantic key.',
+        };
+    });
+    return { suggestions };
+}

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

@@ -1,9 +1,13 @@
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
+export { canonicalizeTagPath } from './model.js';
 export type AddTagInput = {
     name: string;
     userId: string;
     emoji?: string;
 };
+export type ListTagsInput = {
+    userId?: string;
+};
 export type AddTagResult = {
     id: string;
     tag: string;
@@ -16,6 +20,6 @@ export type InspectAddTagResult = {
     restoredPaths: string[];
     emoji: string;
 };
-export declare function listTags(db: AbstractPowerSyncDatabase): Promise<string[]>;
+export declare function listTags(db: AbstractPowerSyncDatabase, input?: ListTagsInput): Promise<string[]>;
 export declare function addTag(db: AbstractPowerSyncDatabase, input: AddTagInput): Promise<AddTagResult>;
 export declare function inspectAddTag(db: AbstractPowerSyncDatabase, input: AddTagInput): Promise<InspectAddTagResult>;