@dinoxx/dinox-cli 2.1.1 → 2.3.0

package/dist/cli.js

@@ -10,12 +10,14 @@ import { registerMetaCommands } from './commands/meta/index.js';
 import { registerNoteCommands } from './commands/notes/index.js';
 import { registerPromptCommands } from './commands/prompt/index.js';
 import { registerSchemaCommands } from './commands/schema/index.js';
+import { registerPropertyCommands } from './commands/properties/index.js';
 import { registerSavedViewCommands } from './commands/savedViews/index.js';
 import { registerSkillsCommands } from './commands/skills/index.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerStorageCommands } from './commands/storage/index.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerTagsCommand } from './commands/tags/index.js';
+import { registerTemplateCommands } from './commands/templates/index.js';
 import { registerTodoCommands } from './commands/todo/index.js';
 import { getPackageVersion } from './utils/version.js';
 import { buildStructuredErrorPayload, DinoxError } from './utils/errors.js';
@@ -85,6 +87,8 @@ export function createCli() {
     registerUpdateCommand(program);
     registerPromptCommands(program);
     registerSavedViewCommands(program);
+    registerPropertyCommands(program);
+    registerTemplateCommands(program);
     registerSchemaCommands(program);
     registerSkillsCommands(program);
     registerStorageCommands(program);

package/dist/commands/domain/options.d.ts

@@ -0,0 +1,10 @@
+export declare function parseIntegerOption(value: string): number;
+export declare function parsePositiveIntegerOption(value: string): number;
+export declare function parseNonNegativeIntegerOption(value: string): number;
+/** Commander collector for repeatable options. */
+export declare function collectOption(value: string, previous: unknown): string[];
+export declare function parseTimeZoneOption(value: string): string;
+/** Reads an inline JSON value or `@file` and parses it. */
+export declare function readJsonOption(value: unknown, label: string, schemaPath: string): Promise<unknown>;
+export declare function requiredArgument(value: string | undefined, label: string): string;
+export declare function assertExclusive(conflicts: Array<[boolean, string]>): void;

package/dist/commands/domain/options.js

@@ -0,0 +1,75 @@
+// Option parsers shared by the commands backed by the vendored desktop domain
+// (view, prop, template).
+import { readStringOrFile } from '../../utils/argValue.js';
+import { DinoxError } from '../../utils/errors.js';
+export function parseIntegerOption(value) {
+    const normalized = value.trim();
+    if (!/^-?\d+$/.test(normalized)) {
+        throw new DinoxError('Expected an integer', { code: 'USAGE_ERROR' });
+    }
+    const parsed = Number(normalized);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new DinoxError('Expected a safe integer', { code: 'USAGE_ERROR' });
+    }
+    return parsed;
+}
+export function parsePositiveIntegerOption(value) {
+    const parsed = parseIntegerOption(value);
+    if (parsed <= 0)
+        throw new DinoxError('Expected a positive integer', { code: 'USAGE_ERROR' });
+    return parsed;
+}
+export function parseNonNegativeIntegerOption(value) {
+    const parsed = parseIntegerOption(value);
+    if (parsed < 0)
+        throw new DinoxError('Expected a non-negative integer', { code: 'USAGE_ERROR' });
+    return parsed;
+}
+/** Commander collector for repeatable options. */
+export function collectOption(value, previous) {
+    return [...(Array.isArray(previous) ? previous : []), value];
+}
+export function parseTimeZoneOption(value) {
+    const normalized = value.trim();
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: normalized });
+    }
+    catch {
+        throw new DinoxError(`Invalid IANA time zone: ${value}`, { code: 'SAVED_VIEW_INVALID_TIME_ZONE' });
+    }
+    return normalized;
+}
+/** Reads an inline JSON value or `@file` and parses it. */
+export async function readJsonOption(value, label, schemaPath) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new DinoxError(`${label} requires inline JSON or @file`, { code: 'USAGE_ERROR' });
+    }
+    let raw;
+    try {
+        raw = await readStringOrFile(value);
+    }
+    catch (error) {
+        throw new DinoxError(`Failed to read ${label}`, { code: 'USAGE_ERROR', cause: error });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new DinoxError(`${label} must be valid JSON`, {
+            code: 'USAGE_ERROR',
+            cause: error,
+            suggestion: `Pass inline JSON or use @file. See \`dino schema ${schemaPath} --format json\`.`,
+        });
+    }
+}
+export function requiredArgument(value, label) {
+    const normalized = value?.trim();
+    if (!normalized)
+        throw new DinoxError(`${label} is required`, { code: 'USAGE_ERROR' });
+    return normalized;
+}
+export function assertExclusive(conflicts) {
+    const conflict = conflicts.find(([active]) => active);
+    if (conflict)
+        throw new DinoxError(conflict[1], { code: 'USAGE_ERROR' });
+}

package/dist/commands/domain/run.d.ts

@@ -0,0 +1,24 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import { type z } from 'zod';
+import { DinoxError } from '../../utils/errors.js';
+export type DomainCommandResult<T> = {
+    result: T;
+    affectedTables: string[];
+};
+/** Converts a desktop domain failure into a DinoxError; DinoxErrors pass through unchanged. */
+export declare function toDinoxError(error: unknown, label?: string): DinoxError;
+export declare function parseDomainInput<T>(definition: {
+    inputSchema: z.ZodType<T>;
+}, input: unknown, label: string): T;
+export declare function runDomainCommand<T>(db: AbstractPowerSyncDatabase, name: string, input: unknown): Promise<DomainCommandResult<T>>;
+export declare function fetchDomainReadModel<T>(db: AbstractPowerSyncDatabase, name: string, input: unknown): Promise<T[]>;
+/** Runs `run` in one read transaction (a consistent snapshot) when the database offers it. */
+export declare function withReadTransaction<T>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<T>): Promise<T>;
+/** Runs `run` in one write transaction; vendored commands called inside reuse it. */
+export declare function withNestedWriteTransaction<T>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<T>): Promise<T>;
+/**
+ * Executes `run` and then `inspect` inside one write transaction that is always rolled
+ * back, so a preview reflects exactly what the real write would do (including desktop
+ * validation and derived values) without persisting or queueing an upload.
+ */
+export declare function previewInRolledBackTransaction<TResult, TPreview>(db: AbstractPowerSyncDatabase, run: (tx: AbstractPowerSyncDatabase) => Promise<TResult>, inspect: (tx: AbstractPowerSyncDatabase, result: TResult) => Promise<TPreview>): Promise<TPreview>;

package/dist/commands/domain/run.js

@@ -0,0 +1,137 @@
+// Runs the vendored desktop domain (src/vendor/electron) against the CLI's PowerSync
+// database: validates inputs with the desktop zod schemas, maps desktop error strings onto
+// registered DinoxError codes, and previews writes by executing them inside a transaction
+// that is always rolled back.
+import { ZodError } from 'zod';
+import { withPowerSyncWriteTransaction } from '../../powersync/runtime.js';
+import { DinoxError } from '../../utils/errors.js';
+import { isRegisteredErrorCode } from '../../utils/errorCodes.js';
+import { createNoteTemplateCommands, createNoteTemplateReadModels } from '../../vendor/electron/domain/note-templates.js';
+import { createPropertyCommands, createPropertyReadModels } from '../../vendor/electron/domain/properties.js';
+import { createSavedViewCommands, createSavedViewReadModels } from '../../vendor/electron/domain/saved-views.js';
+const COMMANDS = new Map([...createPropertyCommands(), ...createSavedViewCommands(), ...createNoteTemplateCommands()]
+    .map((definition) => [definition.name, definition]));
+const READ_MODELS = new Map([...createPropertyReadModels(), ...createSavedViewReadModels(), ...createNoteTemplateReadModels()]
+    .map((definition) => [definition.name, definition]));
+const DOMAIN_CODE_PATTERN = /^[A-Z][A-Z0-9_]+$/;
+function zodIssues(error) {
+    return error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }));
+}
+/** Converts a desktop domain failure into a DinoxError; DinoxErrors pass through unchanged. */
+export function toDinoxError(error, label = 'Dinox domain operation') {
+    if (error instanceof DinoxError)
+        return error;
+    if (error instanceof ZodError) {
+        return new DinoxError(`${label} input is invalid`, {
+            code: 'INVALID_ARGUMENT',
+            details: { issues: zodIssues(error) },
+            recoverable: false,
+        });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (DOMAIN_CODE_PATTERN.test(message) && isRegisteredErrorCode(message)) {
+        return new DinoxError(message, { code: message, cause: error, recoverable: false });
+    }
+    if (/^Note not found: /.test(message)) {
+        return new DinoxError(message, { code: 'NOTE_NOT_FOUND', cause: error });
+    }
+    if (/^Invalid note template .* input$/.test(message)) {
+        return new DinoxError(message, { code: 'INVALID_ARGUMENT', cause: error, recoverable: false });
+    }
+    return new DinoxError(message || `${label} failed`, { code: 'COMMAND_FAILED', cause: error });
+}
+function requireCommand(name) {
+    const definition = COMMANDS.get(name);
+    if (!definition)
+        throw new DinoxError(`Unknown domain command: ${name}`, { code: 'INTERNAL_ERROR' });
+    return definition;
+}
+function requireReadModel(name) {
+    const definition = READ_MODELS.get(name);
+    if (!definition)
+        throw new DinoxError(`Unknown domain read model: ${name}`, { code: 'INTERNAL_ERROR' });
+    return definition;
+}
+export function parseDomainInput(definition, input, label) {
+    const parsed = definition.inputSchema.safeParse(input);
+    if (!parsed.success)
+        throw toDinoxError(parsed.error, label);
+    return parsed.data;
+}
+export async function runDomainCommand(db, name, input) {
+    const definition = requireCommand(name);
+    const parsed = parseDomainInput(definition, input, name);
+    try {
+        return await definition.run(db, parsed);
+    }
+    catch (error) {
+        throw toDinoxError(error, name);
+    }
+}
+export async function fetchDomainReadModel(db, name, input) {
+    const definition = requireReadModel(name);
+    const parsed = parseDomainInput(definition, input, name);
+    try {
+        return await definition.fetch(db, parsed);
+    }
+    catch (error) {
+        throw toDinoxError(error, name);
+    }
+}
+/**
+ * Exposes an open transaction as a database whose nested write/read transactions reuse it,
+ * so vendored commands that open their own transaction run inside the caller's.
+ */
+function nestedDatabase(tx) {
+    const proxy = new Proxy(tx, {
+        get(target, property, receiver) {
+            if (property === 'writeTransaction' || property === 'readTransaction') {
+                return async (run) => run(proxy);
+            }
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+    return proxy;
+}
+/** Runs `run` in one read transaction (a consistent snapshot) when the database offers it. */
+export async function withReadTransaction(db, run) {
+    const candidate = db;
+    if (typeof candidate.readTransaction !== 'function')
+        return run(db);
+    return candidate.readTransaction.call(db, (tx) => run(nestedDatabase(tx)));
+}
+/** Runs `run` in one write transaction; vendored commands called inside reuse it. */
+export async function withNestedWriteTransaction(db, run) {
+    try {
+        return await withPowerSyncWriteTransaction(db, (tx) => run(nestedDatabase(tx)));
+    }
+    catch (error) {
+        throw toDinoxError(error);
+    }
+}
+class DryRunRollback extends Error {
+}
+/**
+ * Executes `run` and then `inspect` inside one write transaction that is always rolled
+ * back, so a preview reflects exactly what the real write would do (including desktop
+ * validation and derived values) without persisting or queueing an upload.
+ */
+export async function previewInRolledBackTransaction(db, run, inspect) {
+    let preview = null;
+    try {
+        await withPowerSyncWriteTransaction(db, async (tx) => {
+            const nested = nestedDatabase(tx);
+            const result = await run(nested);
+            preview = { value: await inspect(nested, result) };
+            throw new DryRunRollback('dry-run rollback');
+        });
+    }
+    catch (error) {
+        if (!(error instanceof DryRunRollback))
+            throw toDinoxError(error);
+    }
+    if (!preview)
+        throw new DinoxError('Dry-run preview did not complete', { code: 'INTERNAL_ERROR' });
+    return preview.value;
+}

package/dist/commands/notes/actions.js

@@ -15,6 +15,8 @@ import { parseNoteSearchFields, projectNoteSearchFields } from './searchOutput.j
 import { parseCreatedAtRange } from './searchTime.js';
 import { buildNoteSearchResponse, normalizeDaysForMeta } from './searchResponse.js';
 import { parseMutationListInput, parseNoteType, parsePreviewLineCount, parseSearchLimit, parseSearchListInput, parseSearchOffset, parseStarredOption, parseStringInput, parseStringListInput, parseTargetNoteIds, syncBeforeNoteCommand, withNoteDatabase, } from './runtime.js';
+import { readNoteProperties } from '../properties/repo.js';
+import { createNoteWithSeed, previewNoteCreateProperties, resolveNoteCreateSeed } from './createFromTemplate.js';
 function toPublicNoteContext(note) {
     if (!note) {
         return null;
@@ -39,11 +41,17 @@ async function executeNoteUpdateOperation(args) {
         await syncBeforeNoteCommand(runtime);
         const durability = resolveWriteDurabilityForRuntime(runtime, args.durability);
         const ids = await parseTargetNoteIds(args.id, args.idsOption, 'update');
+        const hasTitle = typeof args.title === 'string';
         const hasTags = typeof args.tagsOption === 'string';
         const hasBoxes = typeof args.boxOption === 'string';
         const hasStarred = typeof args.starred === 'boolean';
-        if (!hasTags && !hasBoxes && !hasStarred) {
-            throw new DinoxError('At least one option is required: --tags, --boxes, or --starred');
+        if (!hasTitle && !hasTags && !hasBoxes && !hasStarred) {
+            throw new DinoxError('At least one option is required: --title, --tags, --boxes, or --starred');
+        }
+        if (hasTitle && ids.length !== 1) {
+            throw new DinoxError('--title can only be used with a single note id; run one `dino note update <id> --title` per note', {
+                code: 'USAGE_ERROR',
+            });
         }
         const requestedTags = hasTags
             ? await parseMutationListInput(args.tagsOption, '--tags')
@@ -68,6 +76,7 @@ async function executeNoteUpdateOperation(args) {
                 offline,
                 userId: tagUserId,
                 ids,
+                title: args.title,
                 tagsInput: tags,
                 zettelBoxNames: requestedBoxNames,
                 starred: hasStarred ? args.starred : undefined,
@@ -81,6 +90,7 @@ async function executeNoteUpdateOperation(args) {
         for (const targetId of ids) {
             results.push(await updateNote(db, {
                 id: targetId,
+                title: args.title,
                 tags,
                 zettelBoxIds,
                 starred: hasStarred ? args.starred : undefined,
@@ -98,6 +108,7 @@ async function executeNoteUpdateOperation(args) {
             results: results.map((item) => ({
                 id: item.id,
                 updated: item.updated,
+                title: item.title,
                 tags: item.tags,
                 boxes: item.zettelBoxIds,
                 is_starred: item.is_starred,
@@ -359,14 +370,31 @@ export async function runNoteDetail({ command, options, args }) {
 export async function runNoteCreate({ command, options }) {
     const createOptions = options;
     const structuredOutput = getRequestedStructuredOutputFormat() !== null;
+    if (createOptions.content === undefined && !createOptions.template) {
+        throw new DinoxError('--content is required unless --template is given', { code: 'USAGE_ERROR' });
+    }
     await withNoteDatabase(command, async (runtime) => {
         const { db, config, offline } = runtime;
         await syncBeforeNoteCommand(runtime);
         const durability = resolveWriteDurabilityForRuntime(runtime, createOptions.durability);
         const identity = await resolveAuthIdentity(config);
-        const contentMd = await parseStringInput(String(createOptions.content));
-        const canonicalContentMd = await canonicalizeBidlinksInMarkdown(db, contentMd, identity.userId);
-        const { contentJson, contentText } = convertMarkdownToNoteContent(canonicalContentMd);
+        const seed = await resolveNoteCreateSeed(db, {
+            userId: identity.userId,
+            templateId: createOptions.template,
+            properties: createOptions.properties,
+        });
+        // Template content is used as the hydrated Tiptap document itself (as desktop does), so
+        // only explicit --content goes through Markdown conversion.
+        const useTemplateContent = createOptions.content === undefined && seed.templateContent !== null;
+        const contentMd = useTemplateContent
+            ? seed.templateContent.contentMd
+            : createOptions.content !== undefined ? await parseStringInput(String(createOptions.content)) : '';
+        const canonicalContentMd = useTemplateContent
+            ? contentMd
+            : await canonicalizeBidlinksInMarkdown(db, contentMd, identity.userId);
+        const { contentJson, contentText } = useTemplateContent
+            ? { contentJson: seed.templateContent.contentJson, contentText: seed.templateContent.contentText }
+            : convertMarkdownToNoteContent(canonicalContentMd);
         const tagsInput = typeof createOptions.tags === 'string'
             ? await parseStringListInput(createOptions.tags, '--tags')
             : [];
@@ -374,8 +402,21 @@ export async function runNoteCreate({ command, options }) {
             ? await parseStringListInput(createOptions.boxes, '--boxes')
             : [];
         const noteType = parseNoteType(createOptions.type);
+        const id = generateId();
+        const insert = async (tx) => createNote(tx, {
+            id,
+            title: String(createOptions.title),
+            noteType,
+            contentMd: canonicalContentMd,
+            contentJson,
+            contentText,
+            tags: await validateTagsForCreate(tx, tagsInput, identity.userId),
+            zettelBoxIds: await resolveZettelBoxIdsForCreate(tx, boxNames),
+            userId: identity.userId,
+            properties: seed.propertiesJson,
+        });
         if (Boolean(createOptions.dryRun)) {
-            printDryRunPreview(await buildNoteCreateDryRunPreview({
+            const preview = await buildNoteCreateDryRunPreview({
                 db,
                 config,
                 offline,
@@ -385,27 +426,24 @@ export async function runNoteCreate({ command, options }) {
                 contentMd,
                 tagsInput,
                 zettelBoxNames: boxNames,
-            }), runtime);
+            });
+            if (seed.template || seed.values) {
+                const properties = await previewNoteCreateProperties(db, { noteId: id, userId: identity.userId, seed, insert });
+                preview.inputs = { ...preview.inputs, ...(seed.template ? { template: { id: seed.template.id, name: seed.template.name } } : {}) };
+                preview.changes = { ...preview.changes, properties: properties.properties };
+            }
+            printDryRunPreview(preview, runtime);
             return;
         }
-        const id = generateId();
-        await createNote(db, {
-            id,
-            title: String(createOptions.title),
-            noteType,
-            contentMd: canonicalContentMd,
-            contentJson,
-            contentText,
-            tags: await validateTagsForCreate(db, tagsInput, identity.userId),
-            zettelBoxIds: await resolveZettelBoxIdsForCreate(db, boxNames),
-            userId: identity.userId,
-        });
+        await createNoteWithSeed(db, { noteId: id, userId: identity.userId, seed, insert });
         const upload = await waitForMutationUpload(runtime, { durability });
         const payload = {
             ok: true,
             id,
+            ...(seed.template ? { template: { id: seed.template.id, name: seed.template.name } } : {}),
+            ...(seed.template || seed.values ? { properties: (await readNoteProperties(db, { userId: identity.userId, noteId: id })).properties } : {}),
             ...(await readNoteWriteReceipt(db, id, {
-                changed: ['title', 'type', 'content_md', 'content_json', 'content_text', 'tags', 'boxes'],
+                changed: ['title', 'type', 'content_md', 'content_json', 'content_text', 'tags', 'boxes', ...(seed.template || seed.values ? ['properties'] : [])],
                 upload,
                 stale: commandStale(runtime),
             })),
@@ -452,6 +490,17 @@ export async function runNoteDelete({ command, options, args }) {
         printStaleCacheWarning(runtime);
     });
 }
+// Titles are single-line metadata; reject input that would render as a multi-line title.
+function parseNoteTitleOption(raw) {
+    const title = raw.trim();
+    if (!title) {
+        throw new DinoxError('--title must not be empty', { code: 'USAGE_ERROR' });
+    }
+    if (/[\u0000-\u001f\u007f]/.test(title)) {
+        throw new DinoxError('--title must be a single line without control characters', { code: 'USAGE_ERROR' });
+    }
+    return title;
+}
 export async function runNoteUpdate({ command, options, args }) {
     const updateOptions = options;
     await executeNoteUpdateOperation({
@@ -463,6 +512,9 @@ export async function runNoteUpdate({ command, options, args }) {
         starred: typeof updateOptions.starred === 'string'
             ? parseStarredOption(updateOptions.starred, '--starred')
             : undefined,
+        title: typeof updateOptions.title === 'string'
+            ? parseNoteTitleOption(updateOptions.title)
+            : undefined,
         tagsOption: updateOptions.tags,
         commandName: 'dino note update',
         actionName: 'update_note',

package/dist/commands/notes/createFromTemplate.d.ts

@@ -0,0 +1,35 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import { type NotePropertiesPatch } from '../../vendor/electron/shared/index.js';
+import { type NotePropertiesView } from '../properties/repo.js';
+import { type NoteTemplateDetail } from '../templates/model.js';
+export type NoteCreateSeed = {
+    template: NoteTemplateDetail | null;
+    /** Hydrated template content projected like stored note content; null without content. */
+    templateContent: {
+        contentJson: unknown;
+        contentMd: string;
+        contentText: string;
+    } | null;
+    /** Serialized `c_note.properties` holding the template's declared empty slots. */
+    propertiesJson: string | null;
+    values: NotePropertiesPatch | null;
+};
+export declare function resolveNoteCreateSeed(db: AbstractPowerSyncDatabase, input: {
+    userId: string;
+    templateId?: string;
+    properties?: unknown;
+}): Promise<NoteCreateSeed>;
+/** Inserts the note and its initial property values atomically. */
+export declare function createNoteWithSeed(db: AbstractPowerSyncDatabase, input: {
+    noteId: string;
+    userId: string;
+    seed: NoteCreateSeed;
+    insert: (tx: AbstractPowerSyncDatabase) => Promise<unknown>;
+}): Promise<void>;
+/** Dry-run: performs the insert and property writes, reads the resulting properties, rolls back. */
+export declare function previewNoteCreateProperties(db: AbstractPowerSyncDatabase, input: {
+    noteId: string;
+    userId: string;
+    seed: NoteCreateSeed;
+    insert: (tx: AbstractPowerSyncDatabase) => Promise<unknown>;
+}): Promise<NotePropertiesView>;

package/dist/commands/notes/createFromTemplate.js

@@ -0,0 +1,58 @@
+// `note create --template/--properties`: seeds a new note the way desktop's "create from
+// template" does — hydrated template content plus the template's property keys declared as
+// empty slots — and optionally writes initial property values in the same transaction.
+import { DinoxError } from '../../utils/errors.js';
+import { applyNotePropertySlotOperation, serializeRawNoteProperties, } from '../../vendor/electron/shared/index.js';
+import { previewInRolledBackTransaction, runDomainCommand, withNestedWriteTransaction } from '../domain/run.js';
+import { readJsonOption } from '../domain/options.js';
+import { readNoteProperties } from '../properties/repo.js';
+import { hydrateNoteTemplateDocument } from '../templates/model.js';
+import { getNoteTemplate } from '../templates/repo.js';
+import { projectNoteContent } from './contentEngine.js';
+export async function resolveNoteCreateSeed(db, input) {
+    const template = input.templateId ? await getNoteTemplate(db, { userId: input.userId, id: input.templateId }) : null;
+    const projection = template?.document ? projectNoteContent(hydrateNoteTemplateDocument(template.document)) : null;
+    const templateContent = projection
+        ? { contentJson: projection.document, contentMd: projection.contentMd, contentText: projection.contentText }
+        : null;
+    const declared = applyNotePropertySlotOperation({}, 'declare', template?.propertyKeys ?? []).next;
+    let values = null;
+    if (input.properties !== undefined) {
+        const raw = await readJsonOption(input.properties, '--properties', 'note.create');
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new DinoxError('--properties must be a JSON object of property key to value', { code: 'USAGE_ERROR' });
+        }
+        values = raw;
+        if (Object.keys(values).length === 0)
+            values = null;
+    }
+    return { template, templateContent, propertiesJson: serializeRawNoteProperties(declared), values };
+}
+async function applyValues(tx, noteId, userId, seed) {
+    if (!seed.values)
+        return;
+    await runDomainCommand(tx, 'notes.updateProperties', {
+        noteId,
+        userId,
+        patch: seed.values,
+        updatedAt: new Date().toISOString(),
+    });
+}
+/** Inserts the note and its initial property values atomically. */
+export async function createNoteWithSeed(db, input) {
+    if (!input.seed.values) {
+        await input.insert(db);
+        return;
+    }
+    await withNestedWriteTransaction(db, async (tx) => {
+        await input.insert(tx);
+        await applyValues(tx, input.noteId, input.userId, input.seed);
+    });
+}
+/** Dry-run: performs the insert and property writes, reads the resulting properties, rolls back. */
+export async function previewNoteCreateProperties(db, input) {
+    return previewInRolledBackTransaction(db, async (tx) => {
+        await input.insert(tx);
+        await applyValues(tx, input.noteId, input.userId, input.seed);
+    }, (tx) => readNoteProperties(tx, { userId: input.userId, noteId: input.noteId }));
+}

package/dist/commands/notes/descriptors.js

@@ -176,10 +176,12 @@ export const noteCommandGroup = {
         },
         {
             name: 'create',
-            description: 'Create a new note from markdown content',
+            description: 'Create a new note from markdown content or a note template',
             options: [
                 { flags: '--title <string>', description: 'Note title', required: true, type: 'string' },
-                { flags: '--content <string|@file>', description: 'Markdown content', required: true, type: 'string' },
+                { flags: '--content <string|@file>', description: 'Markdown content (required unless --template is given; overrides template content)', type: 'string' },
+                { flags: '--template <id>', description: 'Note template id: hydrates its content ({{date}}, {{time}}, ...) and declares its property keys as empty slots', type: 'string' },
+                { flags: '--properties <json|@file>', description: 'Initial property values as a JSON object; validated against property definitions', type: 'string' },
                 { flags: '--type <note|crawl>', description: 'Note type: note or crawl', type: 'string', defaultValue: 'crawl', enum: ['note', 'crawl'] },
                 { flags: '--tags <string|@file>', description: 'Tag list (JSON array or comma/newline-separated)', type: 'string' },
                 { flags: '--boxes <string|@file>', description: 'Box paths or unique names (JSON array or comma/newline-separated)', type: 'string' },
@@ -194,18 +196,22 @@ export const noteCommandGroup = {
                 output: {
                     type: 'structured',
                     summary: 'Creation acknowledgement with write durability, queue state, and note revision receipt',
-                    fields: ['id', ...NOTE_WRITE_RECEIPT_FIELDS],
+                    fields: ['id', 'template', 'properties', ...NOTE_WRITE_RECEIPT_FIELDS],
                 },
-                examples: ['dino note create --title "Weekly note" --content @/tmp/note.md --type note --durability uploaded --format json'],
+                examples: [
+                    'dino note create --title "Weekly note" --content @/tmp/note.md --type note --durability uploaded --format json',
+                    'dino note create --title "Dune" --template <templateId> --properties \'{"rating":5}\' --type note --format json --dry-run',
+                ],
             },
             action: runNoteCreate,
         },
         {
             name: 'update',
-            description: 'Full-replace note metadata for explicit note ids',
+            description: 'Full-replace note metadata (title, tags, boxes, starred) for explicit note ids',
             arguments: [{ syntax: '[id]', description: 'Optional note id for single-note full replacement' }],
             options: [
                 { flags: '--ids <string|@file>', description: 'Batch note ids (JSON array or comma/newline-separated)', type: 'string' },
+                { flags: '--title <title>', description: 'Replace the note title (single note id only; content is unchanged)', type: 'string' },
                 { flags: '--tags <string|@file>', description: 'Replace the entire tag list; use [] to clear all tags', type: 'string' },
                 { flags: '--boxes <string|@file>', description: 'Replace the entire box list; use [] to clear all boxes', type: 'string' },
                 { flags: '--starred <true|false>', description: 'Replace the starred state', type: 'string', enum: ['true', 'false'] },
@@ -224,6 +230,7 @@ export const noteCommandGroup = {
                 },
                 examples: [
                     'dino note update <id> --tags "work,ai" --format json --dry-run',
+                    'dino note update <id> --title "New title" --format json --dry-run',
                     'dino note update --ids @/tmp/note-ids.txt --boxes "Inbox" --starred true --format json',
                 ],
             },

package/dist/commands/notes/dryRun.d.ts

@@ -18,6 +18,7 @@ export declare function buildNoteUpdateDryRunPreview(args: {
     offline: boolean;
     userId?: string;
     ids: string[];
+    title?: string;
     tagsInput?: string[];
     zettelBoxNames?: string[];
     starred?: boolean;

package/dist/commands/notes/dryRun.js

@@ -67,9 +67,14 @@ export async function buildNoteUpdateDryRunPreview(args) {
         const nextBoxes = Array.isArray(args.zettelBoxNames) ? normalizeDistinctStrings(args.zettelBoxNames) : note.zettel_boxes;
         const tagsTo = nextTags ?? currentTags;
         const starredTo = typeof args.starred === 'boolean' ? args.starred : note.is_starred;
+        const titleFrom = note.title ?? '';
+        const titleTo = typeof args.title === 'string' ? args.title : titleFrom;
         return {
             id: note.id,
-            title: note.title ?? '',
+            title: titleFrom,
+            ...(typeof args.title === 'string'
+                ? { title_from: titleFrom, title_to: titleTo, title_changed: titleFrom !== titleTo }
+                : {}),
             tags_from: currentTags,
             tags_to: tagsTo,
             tags_changed: Array.isArray(args.tagsInput) ? !sameNormalizedSet(currentTags, tagsTo) : false,
@@ -81,7 +86,7 @@ export async function buildNoteUpdateDryRunPreview(args) {
             starred_changed: typeof args.starred === 'boolean' ? note.is_starred !== starredTo : false,
         };
     });
-    const changedCount = changes.filter((item) => item.tags_changed || item.boxes_changed || item.starred_changed).length;
+    const changedCount = changes.filter((item) => item.title_changed === true || item.tags_changed || item.boxes_changed || item.starred_changed).length;
     return {
         dry_run: true,
         command: args.commandName,
@@ -91,6 +96,7 @@ export async function buildNoteUpdateDryRunPreview(args) {
         warnings: buildExecutionWarnings(args.config, args.offline),
         inputs: {
             ids: args.ids,
+            ...(typeof args.title === 'string' ? { title: args.title } : {}),
             ...(Array.isArray(args.tagsInput) ? { tags: nextTags } : {}),
             ...(Array.isArray(args.zettelBoxNames) ? { boxes: normalizeDistinctStrings(args.zettelBoxNames) } : {}),
             ...(typeof args.starred === 'boolean' ? { starred: args.starred } : {}),