@dinoxx/dinox-cli 2.1.1 → 2.3.0

package/dist/commands/properties/index.js

@@ -0,0 +1,640 @@
+import { resolveAuthIdentity } from '../../auth/userInfo.js';
+import { printDryRunPreview } from '../../utils/dryRun.js';
+import { DinoxError } from '../../utils/errors.js';
+import { getRequestedStructuredOutputFormat, printHumanReadableLine, printSuccess, } from '../../utils/output.js';
+import { ACTIVE_PROPERTY_TYPES, isPropertyKeyValid, normalizePropertyDefConfig, PROPERTY_OPTION_COLORS, STATUS_PROPERTY_GROUPS, } from '../../vendor/electron/shared/index.js';
+import { registerCommandGroup } from '../descriptor/register.js';
+import { assertExclusive, collectOption, parseIntegerOption, parsePositiveIntegerOption, readJsonOption, requiredArgument, } from '../domain/options.js';
+import { commandStale, printStaleCacheWarning, syncBeforeCommand, waitForMutationUpload, withCommandRuntime, } from '../runtime.js';
+import { FORMAT_OPTIONS, OFFLINE_OPTIONS, REQUIRE_SYNC_OPTIONS, SYNC_TIMEOUT_OPTIONS, } from '../schema/globalOptions.js';
+import { parseExpectedCount } from '../writeConfirmation.js';
+import { WRITE_DURABILITY_OPTION } from '../writeDurability.js';
+import { configureProperty, createProperty, deleteProperty, fillEmptyNoteProperties, listProperties, migrateLegacyOptions, migrationAffectedCount, previewConfigureProperty, previewCreateProperty, previewDeleteProperty, previewMigrateLegacyOptions, readNoteProperties, reorderNotePropertySlots, requireProperty, setNoteProperties, updateNotePropertySlots, } from './repo.js';
+const PROP_GLOBAL_OPTIONS = [
+    ...FORMAT_OPTIONS,
+    ...OFFLINE_OPTIONS,
+    ...REQUIRE_SYNC_OPTIONS,
+    ...SYNC_TIMEOUT_OPTIONS,
+];
+const DRY_RUN_OPTION = { flags: '--dry-run', description: 'Run the write in a rolled-back transaction and preview the result', type: 'boolean' };
+const COLORS = new Set(PROPERTY_OPTION_COLORS);
+const GROUPS = new Set(STATUS_PROPERTY_GROUPS);
+/** Parses `label[:color[:group]]`, peeling recognised color/group suffixes off the right. */
+export function parseOptionSpec(spec) {
+    const parts = spec.split(':');
+    let group;
+    let color;
+    if (parts.length > 1 && GROUPS.has(parts[parts.length - 1].trim()))
+        group = parts.pop().trim();
+    if (parts.length > 1 && COLORS.has(parts[parts.length - 1].trim()))
+        color = parts.pop().trim();
+    const label = parts.join(':').trim();
+    if (!label)
+        throw new DinoxError(`Option label is required: ${spec}`, { code: 'USAGE_ERROR' });
+    return { label, ...(color ? { color } : {}), ...(group ? { group } : {}) };
+}
+/** Parses `key=value`; the value is JSON when it parses as JSON, otherwise a plain string. */
+export function parseAssignment(spec) {
+    const index = spec.indexOf('=');
+    if (index <= 0)
+        throw new DinoxError(`Expected key=value, got: ${spec}`, { code: 'USAGE_ERROR' });
+    const key = spec.slice(0, index).trim();
+    const raw = spec.slice(index + 1);
+    if (!isPropertyKeyValid(key))
+        throw new DinoxError(`Invalid property key: ${key}`, { code: 'USAGE_ERROR' });
+    try {
+        return [key, JSON.parse(raw)];
+    }
+    catch {
+        return [key, raw];
+    }
+}
+function parseBooleanOption(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new DinoxError('Expected true or false', { code: 'USAGE_ERROR' });
+}
+function parseTypeOption(value) {
+    const normalized = value.trim();
+    if (!ACTIVE_PROPERTY_TYPES.includes(normalized)) {
+        throw new DinoxError(`--type must be one of ${ACTIVE_PROPERTY_TYPES.join(', ')}`, { code: 'USAGE_ERROR' });
+    }
+    return normalized;
+}
+async function readConfigOption(value) {
+    if (value === undefined)
+        return undefined;
+    const raw = await readJsonOption(value, '--config', 'prop.create');
+    const config = normalizePropertyDefConfig(raw);
+    if (!config) {
+        throw new DinoxError('--config is not a valid property config envelope', {
+            code: 'PROPERTY_DEF_CONFIG_INVALID',
+            suggestion: 'Use e.g. {"version":1,"type":"date","mode":"datetime"} or {"version":1,"type":"select","mode":"closed"}.',
+        });
+    }
+    return config;
+}
+async function readOptionsJson(value, schemaPath) {
+    if (value === undefined)
+        return undefined;
+    const raw = await readJsonOption(value, '--options', schemaPath);
+    const items = Array.isArray(raw) ? raw : raw?.items;
+    if (!Array.isArray(items)) {
+        throw new DinoxError('--options must be a JSON array of {id?, label, color?, sortRank?, archived?, group?}', { code: 'USAGE_ERROR' });
+    }
+    return items;
+}
+async function readValuesJson(value, label, schemaPath) {
+    const raw = await readJsonOption(value, label, schemaPath);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new DinoxError(`${label} must be a JSON object of property key to value`, { code: 'USAGE_ERROR' });
+    }
+    return raw;
+}
+function stringList(value) {
+    return Array.isArray(value) ? value : [];
+}
+function propertyLine(property) {
+    return `${property.id}\t${property.key}\t${property.type}\t${property.name}`;
+}
+function printNoteProperties(view) {
+    for (const entry of view.entries) {
+        const display = entry.display === null ? '(empty)' : typeof entry.display === 'string' ? entry.display : JSON.stringify(entry.display);
+        printHumanReadableLine(`${entry.key}\t${entry.type}${entry.defined ? '' : '?'}\t${display}`);
+    }
+    if (view.entries.length === 0)
+        printHumanReadableLine('No properties on this note.');
+}
+async function withPropRuntime(context, run) {
+    await withCommandRuntime(context, async (runtime) => {
+        const identity = await resolveAuthIdentity(runtime.config);
+        await syncBeforeCommand(runtime);
+        await run(runtime, identity.userId);
+    });
+}
+async function finishWrite(runtime, options, payload, human) {
+    const receipt = await waitForMutationUpload(runtime, { durability: options.durability });
+    if (getRequestedStructuredOutputFormat()) {
+        printSuccess({ ok: true, stale: commandStale(runtime), ...payload, ...receipt });
+        return;
+    }
+    human();
+    printStaleCacheWarning(runtime);
+}
+async function runPropList(context) {
+    const limit = context.options.limit;
+    await withPropRuntime(context, async (runtime, userId) => {
+        const properties = await listProperties(runtime.db, { userId, limit });
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, stale: commandStale(runtime), count: properties.length, properties });
+            return;
+        }
+        for (const property of properties)
+            printHumanReadableLine(propertyLine(property));
+        if (properties.length === 0)
+            printHumanReadableLine('No property definitions found.');
+        printStaleCacheWarning(runtime);
+    });
+}
+async function runPropGet(context) {
+    const ref = requiredArgument(context.args.ref, 'Property id or key');
+    await withPropRuntime(context, async (runtime, userId) => {
+        const property = await requireProperty(runtime.db, { userId, ref });
+        printSuccess({ ok: true, stale: commandStale(runtime), property });
+    });
+}
+async function runPropCreate(context) {
+    const options = context.options;
+    const key = typeof options.key === 'string' ? options.key : '';
+    if (!isPropertyKeyValid(key)) {
+        throw new DinoxError('--key must be 1-64 characters without leading/trailing spaces, tabs, or newlines', { code: 'USAGE_ERROR' });
+    }
+    assertExclusive([[options.options !== undefined && stringList(options.option).length > 0, '--options cannot be used with --option']]);
+    const optionItems = options.options !== undefined
+        ? await readOptionsJson(options.options, 'prop.create')
+        : stringList(options.option).length > 0 ? stringList(options.option).map(parseOptionSpec) : undefined;
+    const input = {
+        key,
+        ...(typeof options.name === 'string' ? { name: options.name } : {}),
+        ...(options.type === undefined ? {} : { type: parseTypeOption(String(options.type)) }),
+        ...(optionItems === undefined ? {} : { optionItems }),
+        ...(typeof options.uniqueIdPrefix === 'string' ? { uniqueIdPrefix: options.uniqueIdPrefix } : {}),
+        ...(typeof options.description === 'string' ? { description: options.description } : {}),
+        ...(typeof options.icon === 'string' ? { icon: options.icon } : {}),
+        ...(options.source === 'ai' || options.source === 'manual' ? { source: options.source } : {}),
+    };
+    const config = await readConfigOption(options.config);
+    await withPropRuntime(context, async (runtime, userId) => {
+        const createInput = { ...input, userId, ...(config ? { config } : {}) };
+        if (options.dryRun) {
+            const preview = await previewCreateProperty(runtime.db, createInput);
+            printDryRunPreview({
+                dry_run: true,
+                command: 'dino prop create',
+                action: preview.created ? 'create_property' : 'reuse_property',
+                risk: 'write',
+                summary: preview.created
+                    ? `Create ${preview.property.type} property "${key}".`
+                    : `Property "${key}" already exists; new options would be merged into it.`,
+                changes: { created: preview.created, property: preview.property },
+            }, runtime);
+            return;
+        }
+        const result = await createProperty(runtime.db, createInput);
+        await finishWrite(runtime, options, { created: result.created, property: result.property }, () => {
+            printHumanReadableLine(`${result.created ? 'Created' : 'Reused'}\t${propertyLine(result.property)}`);
+        });
+    });
+}
+function optionEdits(options) {
+    const edits = [];
+    for (const spec of stringList(options.addOption))
+        edits.push({ kind: 'add', ...parseOptionSpec(spec) });
+    for (const ref of stringList(options.archiveOption))
+        edits.push({ kind: 'archive', ref });
+    for (const ref of stringList(options.restoreOption))
+        edits.push({ kind: 'restore', ref });
+    for (const spec of stringList(options.renameOption)) {
+        const index = spec.indexOf('=');
+        if (index <= 0)
+            throw new DinoxError(`--rename-option expects <id|label>=<new label>, got: ${spec}`, { code: 'USAGE_ERROR' });
+        edits.push({ kind: 'rename', ref: spec.slice(0, index), label: spec.slice(index + 1) });
+    }
+    for (const spec of stringList(options.optionColor)) {
+        const index = spec.lastIndexOf('=');
+        const color = spec.slice(index + 1).trim();
+        if (index <= 0 || !COLORS.has(color)) {
+            throw new DinoxError(`--option-color expects <id|label>=<${PROPERTY_OPTION_COLORS.join('|')}>, got: ${spec}`, { code: 'USAGE_ERROR' });
+        }
+        edits.push({ kind: 'color', ref: spec.slice(0, index), color: color });
+    }
+    return edits;
+}
+async function runPropUpdate(context) {
+    const ref = requiredArgument(context.args.ref, 'Property id or key');
+    const options = context.options;
+    const edits = optionEdits(options);
+    assertExclusive([
+        [options.options !== undefined && edits.length > 0, '--options cannot be combined with --add-option/--archive-option/--restore-option/--rename-option/--option-color'],
+        [options.config !== undefined && Boolean(options.clearConfig), '--config cannot be used with --clear-config'],
+        [options.description !== undefined && Boolean(options.clearDescription), '--description cannot be used with --clear-description'],
+        [options.icon !== undefined && Boolean(options.clearIcon), '--icon cannot be used with --clear-icon'],
+        [Boolean(options.repairInvalidOptions) && options.options === undefined, '--repair-invalid-options requires --options'],
+    ]);
+    const replacement = await readOptionsJson(options.options, 'prop.update');
+    const config = options.clearConfig ? null : await readConfigOption(options.config);
+    const patch = {
+        ...(typeof options.name === 'string' ? { name: options.name } : {}),
+        ...(options.clearDescription ? { description: null } : typeof options.description === 'string' ? { description: options.description } : {}),
+        ...(options.clearIcon ? { icon: null } : typeof options.icon === 'string' ? { icon: options.icon } : {}),
+        ...(options.showOnCard === undefined ? {} : { showOnCard: options.showOnCard }),
+        ...(options.sortRank === undefined ? {} : { sortRank: options.sortRank }),
+        ...(replacement === undefined ? {} : { options: replacement }),
+        ...(edits.length > 0 ? { optionEdits: edits } : {}),
+        ...(typeof options.uniqueIdPrefix === 'string' ? { uniqueIdPrefix: options.uniqueIdPrefix } : {}),
+        ...(options.repairInvalidOptions ? { repairInvalidOptions: true } : {}),
+        ...(config === undefined ? {} : { config }),
+    };
+    if (Object.keys(patch).length === 0) {
+        throw new DinoxError('At least one property field must be updated', { code: 'USAGE_ERROR' });
+    }
+    await withPropRuntime(context, async (runtime, userId) => {
+        const input = { ...patch, userId, ref };
+        if (options.dryRun) {
+            const preview = await previewConfigureProperty(runtime.db, input);
+            printDryRunPreview({
+                dry_run: true,
+                command: 'dino prop update',
+                action: 'update_property',
+                risk: 'write',
+                summary: `Update property "${preview.before.key}".`,
+                targets: [{ id: preview.before.id, key: preview.before.key }],
+                changes: { changed: preview.changed, before: preview.before, after: preview.property },
+            }, runtime);
+            return;
+        }
+        const result = await configureProperty(runtime.db, input);
+        await finishWrite(runtime, options, { changed: result.changed, property: result.property }, () => {
+            printHumanReadableLine(propertyLine(result.property));
+        });
+    });
+}
+async function runPropDelete(context) {
+    const ref = requiredArgument(context.args.ref, 'Property id or key');
+    const options = context.options;
+    await withPropRuntime(context, async (runtime, userId) => {
+        if (options.dryRun) {
+            const property = await previewDeleteProperty(runtime.db, { userId, ref });
+            printDryRunPreview({
+                dry_run: true,
+                command: 'dino prop delete',
+                action: 'delete_property',
+                risk: 'write',
+                summary: `Soft-delete property "${property.key}". Existing note values are kept and become untyped.`,
+                targets: [{ id: property.id, key: property.key }],
+            }, runtime);
+            return;
+        }
+        const property = await deleteProperty(runtime.db, { userId, ref });
+        await finishWrite(runtime, options, { deleted: true, property }, () => {
+            printHumanReadableLine(`Deleted ${propertyLine(property)}`);
+        });
+    });
+}
+async function runPropMigrateOptions(context) {
+    const options = context.options;
+    const expectedCount = parseExpectedCount(options.expectedCount);
+    await withPropRuntime(context, async (runtime, userId) => {
+        if (options.dryRun) {
+            const result = await previewMigrateLegacyOptions(runtime.db, userId);
+            printDryRunPreview({
+                dry_run: true,
+                command: 'dino prop migrate-options',
+                action: 'migrate_legacy_property_options',
+                risk: 'high-risk-write',
+                summary: 'Assign stable ids to legacy select options and rewrite note values and saved-view filters that reference them.',
+                changes: { ...result, affected_count: migrationAffectedCount(result) },
+            }, runtime);
+            return;
+        }
+        if (!options.confirm)
+            throw new DinoxError('dino prop migrate-options requires --confirm for writes', { code: 'USAGE_ERROR' });
+        if (expectedCount === null)
+            throw new DinoxError('dino prop migrate-options requires --expected-count <n> for writes', { code: 'USAGE_ERROR' });
+        const result = await migrateLegacyOptions(runtime.db, { userId, expectedCount });
+        await finishWrite(runtime, options, { ...result, affected_count: migrationAffectedCount(result) }, () => {
+            printHumanReadableLine(`Migrated ${result.definitionsMigrated} definitions, ${result.notesUpdated} notes, ${result.savedViewsUpdated} views.`);
+        });
+    });
+}
+async function runPropShow(context) {
+    const noteId = requiredArgument(context.args.noteId, 'Note id');
+    await withPropRuntime(context, async (runtime, userId) => {
+        const view = await readNoteProperties(runtime.db, { userId, noteId });
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, stale: commandStale(runtime), ...view });
+            return;
+        }
+        printNoteProperties(view);
+        printStaleCacheWarning(runtime);
+    });
+}
+async function finishNoteMutation(runtime, options, command, summary, mutation) {
+    if (options.dryRun) {
+        printDryRunPreview({
+            dry_run: true,
+            command,
+            action: 'update_note_properties',
+            risk: 'write',
+            summary,
+            targets: [{ id: mutation.before.noteId }],
+            changes: { changed: mutation.changed, before: mutation.before.properties, after: mutation.after.properties, result: mutation.result },
+        }, runtime);
+        return;
+    }
+    const payload = {
+        noteId: mutation.after.noteId,
+        changed: mutation.changed,
+        result: mutation.result,
+        properties: mutation.after.properties,
+        entries: mutation.after.entries,
+    };
+    if (!mutation.changed) {
+        if (getRequestedStructuredOutputFormat()) {
+            printSuccess({ ok: true, stale: commandStale(runtime), ...payload });
+            return;
+        }
+        printHumanReadableLine('No property changes.');
+        return;
+    }
+    await finishWrite(runtime, options, payload, () => printNoteProperties(mutation.after));
+}
+async function runPropSet(context) {
+    const noteId = requiredArgument(context.args.noteId, 'Note id');
+    const options = context.options;
+    const patch = options.patch === undefined ? {} : await readValuesJson(options.patch, '--patch', 'prop.set');
+    for (const spec of stringList(options.set)) {
+        const [key, value] = parseAssignment(spec);
+        patch[key] = value;
+    }
+    for (const key of stringList(options.unset)) {
+        if (!isPropertyKeyValid(key))
+            throw new DinoxError(`Invalid property key: ${key}`, { code: 'USAGE_ERROR' });
+        patch[key] = null;
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new DinoxError('Pass at least one --set key=value, --unset key, or --patch', { code: 'USAGE_ERROR' });
+    }
+    await withPropRuntime(context, async (runtime, userId) => {
+        const mutation = await setNoteProperties(runtime.db, {
+            userId,
+            noteId,
+            patch: patch,
+            dryRun: Boolean(options.dryRun),
+        });
+        await finishNoteMutation(runtime, options, 'dino prop set', `Update ${Object.keys(patch).length} properties on note ${noteId}.`, mutation);
+    });
+}
+async function runPropFill(context) {
+    const noteId = requiredArgument(context.args.noteId, 'Note id');
+    const options = context.options;
+    const values = await readValuesJson(options.values, '--values', 'prop.fill');
+    await withPropRuntime(context, async (runtime, userId) => {
+        const mutation = await fillEmptyNoteProperties(runtime.db, {
+            userId,
+            noteId,
+            values: values,
+            dryRun: Boolean(options.dryRun),
+        });
+        await finishNoteMutation(runtime, options, 'dino prop fill', `Fill empty declared properties on note ${noteId}.`, mutation);
+    });
+}
+async function runPropSlots(context) {
+    const noteId = requiredArgument(context.args.noteId, 'Note id');
+    const options = context.options;
+    const operations = ['declare', 'clear', 'remove'].filter((operation) => stringList(options[operation]).length > 0);
+    const order = stringList(options.order);
+    if (operations.length + (order.length > 0 ? 1 : 0) !== 1) {
+        throw new DinoxError('Pass exactly one of --declare, --clear, --remove, or --order', { code: 'USAGE_ERROR' });
+    }
+    await withPropRuntime(context, async (runtime, userId) => {
+        const operation = operations[0];
+        const mutation = operation
+            ? await updateNotePropertySlots(runtime.db, { userId, noteId, operation, keys: stringList(options[operation]), dryRun: Boolean(options.dryRun) })
+            : await reorderNotePropertySlots(runtime.db, { userId, noteId, orderedKeys: order, dryRun: Boolean(options.dryRun) });
+        await finishNoteMutation(runtime, options, 'dino prop slots', `${operation ?? 'reorder'} property slots on note ${noteId}.`, mutation);
+    });
+}
+const NOTE_MUTATION_FIELDS = ['noteId', 'changed', 'result', 'properties', 'entries', 'durability', 'upload_queue_remaining', 'stale'];
+export const propertyCommandGroup = {
+    name: 'prop',
+    description: 'Manage property definitions and note property values',
+    commands: [
+        {
+            name: 'list',
+            description: 'List property definitions (types, option ids, config)',
+            options: [
+                { flags: '--limit <n>', description: 'Maximum returned definitions (1-5000)', parser: parsePositiveIntegerOption, type: 'number', defaultValue: 1000 },
+            ],
+            schema: {
+                path: 'prop.list',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Property definition catalog in sort order', fields: ['stale', 'count', 'properties'] },
+                examples: ['dino prop list --format json'],
+            },
+            action: runPropList,
+        },
+        {
+            name: 'get',
+            description: 'Get one property definition by id or key',
+            arguments: [{ syntax: '<ref>', description: 'Property definition id or key' }],
+            schema: {
+                path: 'prop.get',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Property definition', fields: ['stale', 'property'] },
+                examples: ['dino prop get 状态 --format json'],
+            },
+            action: runPropGet,
+        },
+        {
+            name: 'create',
+            description: 'Create a property definition, or reuse the existing one with this key (new options are merged)',
+            options: [
+                { flags: '--key <key>', description: 'Stable key stored in note properties; immutable after creation', required: true, type: 'string' },
+                { flags: '--name <name>', description: 'Display name (defaults to the key)', type: 'string' },
+                { flags: '--type <type>', description: `Property type: ${ACTIVE_PROPERTY_TYPES.join(', ')} (defaults to text)`, type: 'string', enum: [...ACTIVE_PROPERTY_TYPES] },
+                { flags: '--option <label[:color[:group]]>', description: 'Add a select/multi_select/status option (repeatable); status defaults to todo/in_progress/complete options', parser: collectOption, type: 'string[]' },
+                { flags: '--options <json|@file>', description: 'Option list JSON: [{label, color?, sortRank?, archived?, group?}]', type: 'string' },
+                { flags: '--config <json|@file>', description: 'Type config envelope, e.g. {"version":1,"type":"date","mode":"datetime"}', type: 'string' },
+                { flags: '--unique-id-prefix <prefix>', description: 'Prefix for unique_id values (A-Z0-9, max 12)', type: 'string' },
+                { flags: '--description <text>', description: 'Semantic description (helps AI fill values)', type: 'string' },
+                { flags: '--icon <icon>', description: 'Icon text', type: 'string' },
+                { flags: '--source <source>', description: 'Definition source: manual or ai', type: 'string', enum: ['manual', 'ai'] },
+                WRITE_DURABILITY_OPTION,
+                DRY_RUN_OPTION,
+            ],
+            schema: {
+                path: 'prop.create',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Created or reused property definition', fields: ['created', 'property', 'durability', 'upload_queue_remaining', 'stale'] },
+                examples: [
+                    'dino prop create --key 状态 --type status --format json --dry-run',
+                    'dino prop create --key priority --type select --option High:red --option Low:gray --format json',
+                    'dino prop create --key due --type date --config \'{"version":1,"type":"date","mode":"datetime"}\' --format json',
+                ],
+            },
+            action: runPropCreate,
+        },
+        {
+            name: 'update',
+            description: 'Update a property definition: name, description, icon, card visibility, order, options, config',
+            arguments: [{ syntax: '<ref>', description: 'Property definition id or key' }],
+            options: [
+                { flags: '--name <name>', description: 'Rename (note data is keyed by the immutable key and is not touched)', type: 'string' },
+                { flags: '--description <text>', description: 'Replace the description', type: 'string' },
+                { flags: '--clear-description', description: 'Clear the description', type: 'boolean' },
+                { flags: '--icon <icon>', description: 'Replace the icon', type: 'string' },
+                { flags: '--clear-icon', description: 'Clear the icon', type: 'boolean' },
+                { flags: '--show-on-card <bool>', description: 'Show on compact note cards: true or false', parser: parseBooleanOption, type: 'boolean' },
+                { flags: '--sort-rank <n>', description: 'Catalog sort rank', parser: parseIntegerOption, type: 'number' },
+                { flags: '--add-option <label[:color[:group]]>', description: 'Append an option (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--archive-option <id|label>', description: 'Archive an option; options are never removed (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--restore-option <id|label>', description: 'Un-archive an option (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--rename-option <id|label=new>', description: 'Relabel an option; stored values keep its id (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--option-color <id|label=color>', description: 'Recolor an option (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--options <json|@file>', description: 'Replace the whole option list; existing options must keep their id (archive instead of removing)', type: 'string' },
+                { flags: '--repair-invalid-options', description: 'With --options: replace malformed stored options by id-less items', type: 'boolean' },
+                { flags: '--unique-id-prefix <prefix>', description: 'Replace the unique_id prefix (issued numbers are kept)', type: 'string' },
+                { flags: '--config <json|@file>', description: 'Replace the type config envelope', type: 'string' },
+                { flags: '--clear-config', description: 'Remove the explicit config and restore the type default', type: 'boolean' },
+                WRITE_DURABILITY_OPTION,
+                DRY_RUN_OPTION,
+            ],
+            schema: {
+                path: 'prop.update',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Updated property definition', fields: ['changed', 'property', 'durability', 'upload_queue_remaining', 'stale'] },
+                examples: [
+                    'dino prop update priority --add-option Medium:yellow --format json --dry-run',
+                    'dino prop update priority --rename-option High=Urgent --archive-option Low --format json',
+                    'dino prop update due --config \'{"version":1,"type":"date","mode":"date"}\' --format json',
+                ],
+            },
+            action: runPropUpdate,
+        },
+        {
+            name: 'delete',
+            description: 'Soft-delete a property definition; note values are kept and shown as untyped',
+            arguments: [{ syntax: '<ref>', description: 'Property definition id or key' }],
+            options: [WRITE_DURABILITY_OPTION, DRY_RUN_OPTION],
+            schema: {
+                path: 'prop.delete',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Deleted property definition', fields: ['deleted', 'property', 'durability', 'upload_queue_remaining', 'stale'] },
+                examples: ['dino prop delete priority --format json --dry-run'],
+            },
+            action: runPropDelete,
+        },
+        {
+            name: 'migrate-options',
+            description: 'Migrate legacy string-array select options to stable option ids (rewrites note values and view filters)',
+            options: [
+                DRY_RUN_OPTION,
+                { flags: '--confirm', description: 'Required for real writes after reviewing a dry run', type: 'boolean' },
+                { flags: '--expected-count <n>', description: 'Must equal the dry run changes.affected_count', type: 'number' },
+                WRITE_DURABILITY_OPTION,
+            ],
+            schema: {
+                path: 'prop.migrate-options',
+                risk: 'high-risk-write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Migration counts', fields: ['definitionsMigrated', 'optionsCreated', 'notesUpdated', 'savedViewsUpdated', 'affected_count', 'durability', 'upload_queue_remaining', 'stale'] },
+                examples: [
+                    'dino prop migrate-options --dry-run --format json',
+                    'dino prop migrate-options --expected-count 42 --confirm --format json',
+                ],
+            },
+            action: runPropMigrateOptions,
+        },
+        {
+            name: 'show',
+            description: 'Show a note\'s property values resolved against their definitions',
+            arguments: [{ syntax: '<noteId>', description: 'Note id' }],
+            schema: {
+                path: 'prop.show',
+                risk: 'read',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Note properties (null = declared empty slot) with typed entries', fields: ['stale', 'noteId', 'valid', 'properties', 'entries'] },
+                examples: ['dino prop show <noteId> --format json'],
+            },
+            action: runPropShow,
+        },
+        {
+            name: 'set',
+            description: 'Set or remove note property values; values are coerced and validated against their definitions',
+            arguments: [{ syntax: '<noteId>', description: 'Note id' }],
+            options: [
+                { flags: '--set <key=value>', description: 'Set a value (repeatable); JSON values are parsed, select options accept a label or id', parser: collectOption, type: 'string[]' },
+                { flags: '--unset <key>', description: 'Remove a property from the note (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--patch <json|@file>', description: 'JSON object of key to value; null removes the key', type: 'string' },
+                WRITE_DURABILITY_OPTION,
+                DRY_RUN_OPTION,
+            ],
+            schema: {
+                path: 'prop.set',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Note properties after the write', fields: NOTE_MUTATION_FIELDS },
+                examples: [
+                    'dino prop set <noteId> --set 状态=进行中 --set rating=4 --format json --dry-run',
+                    'dino prop set <noteId> --patch \'{"due":"2026-10-31","tags":["a","b"]}\' --format json',
+                    'dino prop set <noteId> --unset obsolete --format json',
+                ],
+            },
+            action: runPropSet,
+        },
+        {
+            name: 'fill',
+            description: 'Fill only properties that are declared but still empty on the note; other keys are skipped',
+            arguments: [{ syntax: '<noteId>', description: 'Note id' }],
+            options: [
+                { flags: '--values <json|@file>', description: 'JSON object of key to value', required: true, type: 'string' },
+                WRITE_DURABILITY_OPTION,
+                DRY_RUN_OPTION,
+            ],
+            schema: {
+                path: 'prop.fill',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Applied and skipped keys plus resulting properties', fields: NOTE_MUTATION_FIELDS },
+                examples: ['dino prop fill <noteId> --values \'{"summary":"…","rating":3}\' --format json'],
+            },
+            action: runPropFill,
+        },
+        {
+            name: 'slots',
+            description: 'Declare empty property slots, clear values, remove keys, or reorder keys on a note',
+            arguments: [{ syntax: '<noteId>', description: 'Note id' }],
+            options: [
+                { flags: '--declare <key>', description: 'Add an empty slot for a key (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--clear <key>', description: 'Clear a value but keep the slot (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--remove <key>', description: 'Remove a key and its value (repeatable)', parser: collectOption, type: 'string[]' },
+                { flags: '--order <key>', description: 'Preferred display order of visible keys (repeat in order, at least 2)', parser: collectOption, type: 'string[]' },
+                WRITE_DURABILITY_OPTION,
+                DRY_RUN_OPTION,
+            ],
+            schema: {
+                path: 'prop.slots',
+                risk: 'write',
+                auth: 'required',
+                globalOptions: PROP_GLOBAL_OPTIONS,
+                output: { type: 'structured', summary: 'Note properties after the slot change', fields: NOTE_MUTATION_FIELDS },
+                examples: [
+                    'dino prop slots <noteId> --declare 状态 --declare due --format json',
+                    'dino prop slots <noteId> --order due --order 状态 --format json',
+                ],
+            },
+            action: runPropSlots,
+        },
+    ],
+};
+export function registerPropertyCommands(program) {
+    registerCommandGroup(program, propertyCommandGroup);
+}