@taskset/cli 4.0.0 → 6.0.0

package/dist/cli.js

@@ -1,11 +1,11 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { DocumentStatusSchema, TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
-import { buildTaskIndex, createDocument, createSnapshot, createTask, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateTask, } from '@taskset/core';
+import { DocumentIdSchema, DocumentStatusSchema, DocumentTimestampSchema, TaskIdSchema, TaskPrioritySchema, TaskRiskSchema, TaskStatusSchema, TaskTimestampSchema, } from '@taskset/contracts';
+import { buildDocumentGraph, buildTaskIndex, createDocument, createSnapshot, createTask, DOCUMENT_SORT_DIRECTIONS, DOCUMENT_SORT_KEYS, DocumentQuerySchema, deleteDocument, deleteTask, diagnoseRepository, discoverRepository, executeDocumentBatch, generateViews, importDocument, initializeRepository, listDocuments, listSnapshots, migrateTaskIds, normalizeDocumentKind, normalizeRepositoryPath, queryDocuments, queryTasks, RepositoryPathError, readDocument, readTask, restoreSnapshot, serializeDocumentFile, serializeTaskFile, syncRepository, TASK_SORT_DIRECTIONS, TASK_SORT_KEYS, TaskQuerySchema, updateDocument, updateTask, } from '@taskset/core';
 import * as z from 'zod';
 const USAGE = `Usage:
-  taskset init [--cwd <path>]
+  taskset init [--config] [--cwd <path>]
   taskset config [--json] [--cwd <path>]
   taskset doctor [--json] [--cwd <path>]
   taskset generate [--json] [--cwd <path>]
@@ -19,17 +19,20 @@ const USAGE = `Usage:
   taskset task delete <task-id> [--remove-dependencies] [--json] [--cwd <path>]
   taskset task migrate-ids [--json] [--cwd <path>]
   taskset sync [--concurrency <count>] [--json] [--cwd <path>]
-  taskset document create <story|flow|decision|adr|dr|research|runbook> --title <title>
+  taskset document create <story|flow|decision|adr|dr|research|runbook> --title <title> [metadata options]
   taskset document import <markdown-path> [--type <type>] [--move]
   taskset document batch <manifest.json> [--concurrency <count>] [--json]
-  taskset document list [type] [--json] [--cwd <path>]
-  taskset document show <document-id> [--type <type>] [--json] [--cwd <path>]
+  taskset document list [type] [query options]
+  taskset document show <document-id> [--type <type>] [--include-derived] [--json]
+  taskset document update <document-id> [metadata options] [--type <type>]
+  taskset document status <document-id> <status> [--type <type>] [--json]
+  taskset document delete <document-id> [--type <type>] [--remove-dependencies] [--json]
 
 Metadata options:
   --status --priority --order --owner --team --estimate --effort --risk --due-date
   --label --assignee --reviewer --depends-on --related --duplicate
   --parent --file --directory --project --body
-  Repeat array options. Task updates clear arrays with --clear-dependencies,
+  Repeat array options. Task and document updates clear arrays with --clear-dependencies,
   --clear-labels, --clear-assignees, --clear-reviewers, --clear-related,
   --clear-files, --clear-directories, or --clear-projects. Clear scalar
   relationships with --clear-parent or --clear-owner.
@@ -64,6 +67,10 @@ const CommonValuesSchema = z.strictObject({
     cwd: CwdSchema,
     json: JsonSchema,
 });
+const InitValuesSchema = z.strictObject({
+    cwd: CwdSchema,
+    config: z.boolean().optional(),
+});
 const ConcurrencySchema = z.coerce.number().int().min(1).max(32).optional();
 const DocumentKindInputSchema = TrimmedStringSchema.transform((value, context) => {
     try {
@@ -81,17 +88,51 @@ const DocumentInputSchema = z.strictObject({
     type: DocumentKindInputSchema,
     title: TrimmedStringSchema,
     status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.number().finite().nonnegative().optional(),
     labels: StringListSchema.optional(),
-    related: StringListSchema.optional(),
+    dependsOn: TaskIdListSchema.optional(),
+    files: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignees: StringListSchema.optional(),
+    reviewers: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.number().int().nonnegative().optional(),
+    effort: z.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    dueDate: DocumentTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicates: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directories: StringListSchema.optional(),
+    projects: StringListSchema.optional(),
     body: z.string().optional(),
 });
-const DocumentUpdateSchema = z.strictObject({
+const DocumentUpdateSchema = z
+    .strictObject({
     title: TrimmedStringSchema.optional(),
     status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.nullable().optional(),
+    order: z.number().finite().nonnegative().nullable().optional(),
     labels: StringListSchema.optional(),
-    related: StringListSchema.optional(),
+    dependsOn: TaskIdListSchema.optional(),
+    files: StringListSchema.optional(),
+    owner: TrimmedStringSchema.nullable().optional(),
+    assignees: StringListSchema.optional(),
+    reviewers: StringListSchema.optional(),
+    team: TrimmedStringSchema.nullable().optional(),
+    estimate: z.number().int().nonnegative().nullable().optional(),
+    effort: z.number().finite().nonnegative().nullable().optional(),
+    risk: TaskRiskSchema.nullable().optional(),
+    dueDate: DocumentTimestampSchema.nullable().optional(),
+    related: TaskIdListSchema.optional(),
+    duplicates: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.nullable().optional(),
+    directories: StringListSchema.optional(),
+    projects: StringListSchema.optional(),
     body: z.string().optional(),
-});
+})
+    .refine((input) => Object.keys(input).length > 0, 'Document update requires at least one field');
 const DocumentBatchSchema = z
     .array(z.discriminatedUnion('action', [
     z.strictObject({ action: z.literal('create'), input: DocumentInputSchema }),
@@ -121,6 +162,148 @@ const DocumentBatchSchema = z
     }),
 ]))
     .min(1);
+const UPDATE_CLEAR_PAIRS = [
+    ['priority', 'clear-priority'],
+    ['order', 'clear-order'],
+    ['label', 'clear-labels'],
+    ['depends-on', 'clear-dependencies'],
+    ['file', 'clear-files'],
+    ['owner', 'clear-owner'],
+    ['assignee', 'clear-assignees'],
+    ['reviewer', 'clear-reviewers'],
+    ['team', 'clear-team'],
+    ['estimate', 'clear-estimate'],
+    ['effort', 'clear-effort'],
+    ['risk', 'clear-risk'],
+    ['due-date', 'clear-due-date'],
+    ['related', 'clear-related'],
+    ['duplicate', 'clear-duplicates'],
+    ['parent', 'clear-parent'],
+    ['directory', 'clear-directories'],
+    ['project', 'clear-projects'],
+];
+const DocumentCreateValuesSchema = z.strictObject({
+    title: TrimmedStringSchema,
+    status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.coerce.number().finite().nonnegative().optional(),
+    label: StringListSchema.optional(),
+    'depends-on': TaskIdListSchema.optional(),
+    file: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.coerce.number().int().nonnegative().optional(),
+    effort: z.coerce.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    'due-date': DocumentTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicate: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directory: StringListSchema.optional(),
+    project: StringListSchema.optional(),
+    body: z.string().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+});
+const DocumentUpdateValuesSchema = z
+    .strictObject({
+    title: TrimmedStringSchema.optional(),
+    status: DocumentStatusSchema.optional(),
+    priority: TaskPrioritySchema.optional(),
+    order: z.coerce.number().finite().nonnegative().optional(),
+    label: StringListSchema.optional(),
+    'depends-on': TaskIdListSchema.optional(),
+    file: StringListSchema.optional(),
+    owner: TrimmedStringSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: TrimmedStringSchema.optional(),
+    estimate: z.coerce.number().int().nonnegative().optional(),
+    effort: z.coerce.number().finite().nonnegative().optional(),
+    risk: TaskRiskSchema.optional(),
+    'due-date': DocumentTimestampSchema.optional(),
+    related: TaskIdListSchema.optional(),
+    duplicate: TaskIdListSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    directory: StringListSchema.optional(),
+    project: StringListSchema.optional(),
+    body: z.string().optional(),
+    type: TrimmedStringSchema.optional(),
+    'clear-priority': z.boolean().optional(),
+    'clear-order': z.boolean().optional(),
+    'clear-labels': z.boolean().optional(),
+    'clear-dependencies': z.boolean().optional(),
+    'clear-files': z.boolean().optional(),
+    'clear-owner': z.boolean().optional(),
+    'clear-assignees': z.boolean().optional(),
+    'clear-reviewers': z.boolean().optional(),
+    'clear-team': z.boolean().optional(),
+    'clear-estimate': z.boolean().optional(),
+    'clear-effort': z.boolean().optional(),
+    'clear-risk': z.boolean().optional(),
+    'clear-due-date': z.boolean().optional(),
+    'clear-related': z.boolean().optional(),
+    'clear-duplicates': z.boolean().optional(),
+    'clear-parent': z.boolean().optional(),
+    'clear-directories': z.boolean().optional(),
+    'clear-projects': z.boolean().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+})
+    .superRefine((values, context) => {
+    for (const [valueKey, clearKey] of UPDATE_CLEAR_PAIRS) {
+        if (values[valueKey] !== undefined && values[clearKey]) {
+            context.addIssue({
+                code: 'custom',
+                path: [clearKey],
+                message: `Cannot set and clear ${valueKey} in the same update`,
+            });
+        }
+    }
+    const nonControlKeys = Object.keys(values).filter((key) => key !== 'cwd' && key !== 'json' && key !== 'type');
+    if (nonControlKeys.length === 0) {
+        context.addIssue({
+            code: 'custom',
+            message: 'Document update requires at least one field option',
+        });
+    }
+});
+const DocumentListValuesSchema = z.strictObject({
+    status: z.array(DocumentStatusSchema).optional(),
+    priority: z.array(TaskPrioritySchema).optional(),
+    label: StringListSchema.optional(),
+    owner: StringListSchema.optional(),
+    assignee: StringListSchema.optional(),
+    reviewer: StringListSchema.optional(),
+    team: StringListSchema.optional(),
+    risk: z.array(TaskRiskSchema).optional(),
+    project: StringListSchema.optional(),
+    'depends-on': TaskIdSchema.optional(),
+    related: TaskIdSchema.optional(),
+    duplicate: TaskIdSchema.optional(),
+    parent: TaskIdSchema.optional(),
+    file: StringListSchema.optional(),
+    directory: StringListSchema.optional(),
+    'estimate-min': z.coerce.number().finite().nonnegative().optional(),
+    'estimate-max': z.coerce.number().finite().nonnegative().optional(),
+    'effort-min': z.coerce.number().finite().nonnegative().optional(),
+    'effort-max': z.coerce.number().finite().nonnegative().optional(),
+    'due-before': DocumentTimestampSchema.optional(),
+    'due-after': DocumentTimestampSchema.optional(),
+    'created-before': DocumentTimestampSchema.optional(),
+    'created-after': DocumentTimestampSchema.optional(),
+    'updated-before': DocumentTimestampSchema.optional(),
+    'updated-after': DocumentTimestampSchema.optional(),
+    search: z.string().optional(),
+    sort: z.enum(DOCUMENT_SORT_KEYS).optional(),
+    direction: z.enum(DOCUMENT_SORT_DIRECTIONS).optional(),
+    impact: z.boolean().optional(),
+    'include-derived': z.boolean().optional(),
+    cwd: CwdSchema,
+    json: JsonSchema,
+});
 const CreateValuesSchema = z.strictObject({
     title: TrimmedStringSchema,
     status: TaskStatusSchema.optional(),
@@ -146,26 +329,6 @@ const CreateValuesSchema = z.strictObject({
     cwd: CwdSchema,
     json: JsonSchema,
 });
-const UPDATE_CLEAR_PAIRS = [
-    ['priority', 'clear-priority'],
-    ['order', 'clear-order'],
-    ['label', 'clear-labels'],
-    ['depends-on', 'clear-dependencies'],
-    ['file', 'clear-files'],
-    ['owner', 'clear-owner'],
-    ['assignee', 'clear-assignees'],
-    ['reviewer', 'clear-reviewers'],
-    ['team', 'clear-team'],
-    ['estimate', 'clear-estimate'],
-    ['effort', 'clear-effort'],
-    ['risk', 'clear-risk'],
-    ['due-date', 'clear-due-date'],
-    ['related', 'clear-related'],
-    ['duplicate', 'clear-duplicates'],
-    ['parent', 'clear-parent'],
-    ['directory', 'clear-directories'],
-    ['project', 'clear-projects'],
-];
 const UpdateValuesSchema = z
     .strictObject({
     title: TrimmedStringSchema.optional(),
@@ -328,6 +491,13 @@ function taskRecordJson(record, derived) {
         ...(derived ? { derived } : {}),
     };
 }
+function documentRecordJson(record, derived) {
+    return {
+        relativePath: record.relativePath,
+        ...record.document.metadata,
+        ...(derived ? { derived } : {}),
+    };
+}
 function writeTaskRecord(record, json, stdout) {
     if (json) {
         stdout(`${JSON.stringify(taskRecordJson(record), null, 2)}\n`);
@@ -336,6 +506,14 @@ function writeTaskRecord(record, json, stdout) {
         stdout(`${record.task.metadata.id}\n`);
     }
 }
+function writeDocumentRecord(record, json, stdout) {
+    if (json) {
+        stdout(`${JSON.stringify(documentRecordJson(record), null, 2)}\n`);
+    }
+    else {
+        stdout(`${record.document.metadata.id}\n`);
+    }
+}
 function warningWriter(stderr) {
     return (warning) => stderr(`warning: ${warning.message}\n`);
 }
@@ -439,6 +617,103 @@ function updateInputFromValues(repository, values) {
         ...(values.body !== undefined ? { body: values.body } : {}),
     };
 }
+function documentUpdateInputFromValues(repository, values) {
+    return {
+        ...(values.title !== undefined ? { title: values.title } : {}),
+        ...(values.status !== undefined ? { status: values.status } : {}),
+        ...(values['clear-priority']
+            ? { priority: null }
+            : values.priority !== undefined
+                ? { priority: values.priority }
+                : {}),
+        ...(values['clear-order']
+            ? { order: null }
+            : values.order !== undefined
+                ? { order: values.order }
+                : {}),
+        ...(values['clear-labels']
+            ? { labels: [] }
+            : values.label !== undefined
+                ? { labels: values.label }
+                : {}),
+        ...(values['clear-dependencies']
+            ? { dependsOn: [] }
+            : values['depends-on'] !== undefined
+                ? { dependsOn: values['depends-on'] }
+                : {}),
+        ...(values['clear-files']
+            ? { files: [] }
+            : values.file !== undefined
+                ? { files: normalizeMutationPaths(repository, values.file) }
+                : {}),
+        ...(values['clear-owner']
+            ? { owner: null }
+            : values.owner !== undefined
+                ? { owner: values.owner }
+                : {}),
+        ...(values['clear-assignees']
+            ? { assignees: [] }
+            : values.assignee !== undefined
+                ? { assignees: values.assignee }
+                : {}),
+        ...(values['clear-reviewers']
+            ? { reviewers: [] }
+            : values.reviewer !== undefined
+                ? { reviewers: values.reviewer }
+                : {}),
+        ...(values['clear-team']
+            ? { team: null }
+            : values.team !== undefined
+                ? { team: values.team }
+                : {}),
+        ...(values['clear-estimate']
+            ? { estimate: null }
+            : values.estimate !== undefined
+                ? { estimate: values.estimate }
+                : {}),
+        ...(values['clear-effort']
+            ? { effort: null }
+            : values.effort !== undefined
+                ? { effort: values.effort }
+                : {}),
+        ...(values['clear-risk']
+            ? { risk: null }
+            : values.risk !== undefined
+                ? { risk: values.risk }
+                : {}),
+        ...(values['clear-due-date']
+            ? { dueDate: null }
+            : values['due-date'] !== undefined
+                ? { dueDate: values['due-date'] }
+                : {}),
+        ...(values['clear-related']
+            ? { related: [] }
+            : values.related !== undefined
+                ? { related: values.related }
+                : {}),
+        ...(values['clear-duplicates']
+            ? { duplicates: [] }
+            : values.duplicate !== undefined
+                ? { duplicates: values.duplicate }
+                : {}),
+        ...(values['clear-parent']
+            ? { parent: null }
+            : values.parent !== undefined
+                ? { parent: values.parent }
+                : {}),
+        ...(values['clear-directories']
+            ? { directories: [] }
+            : values.directory !== undefined
+                ? { directories: normalizeMutationPaths(repository, values.directory) }
+                : {}),
+        ...(values['clear-projects']
+            ? { projects: [] }
+            : values.project !== undefined
+                ? { projects: values.project }
+                : {}),
+        ...(values.body !== undefined ? { body: values.body } : {}),
+    };
+}
 export async function runCli(args, context = {}) {
     const cwd = path.resolve(context.cwd ?? process.cwd());
     const stdout = context.stdout ?? ((value) => process.stdout.write(value));
@@ -453,6 +728,23 @@ export async function runCli(args, context = {}) {
             return 0;
         }
         if (command === 'init' || command === 'config' || command === 'doctor') {
+            if (command === 'init') {
+                const parsed = parseArgs({
+                    args: commandArgs,
+                    allowPositionals: false,
+                    options: {
+                        cwd: { type: 'string' },
+                        config: { type: 'boolean' },
+                    },
+                });
+                const values = parseSchema(InitValuesSchema, parsed.values, 'init options');
+                const commandCwd = resolveCommandCwd(cwd, values.cwd);
+                const repository = await initializeRepository(commandCwd, {
+                    writeConfig: values.config === true,
+                });
+                stdout(`Initialized Taskset in ${repository.rootDirectory}\n`);
+                return 0;
+            }
             const parsed = parseArgs({
                 args: commandArgs,
                 allowPositionals: false,
@@ -460,24 +752,23 @@ export async function runCli(args, context = {}) {
             });
             const values = parseSchema(CommonValuesSchema, parsed.values, `${command} options`);
             const commandCwd = resolveCommandCwd(cwd, values.cwd);
-            if (command === 'init') {
-                const repository = await initializeRepository(commandCwd);
-                stdout(`Initialized Taskset in ${repository.rootDirectory}\n`);
-                return 0;
-            }
             const repository = await discoverRepository(commandCwd);
             if (command === 'config') {
                 if (values.json) {
                     stdout(`${JSON.stringify({
                         rootDirectory: repository.rootDirectory,
                         configPath: repository.configPath,
+                        hasConfig: repository.hasConfig,
                         dataDirectory: repository.dataDirectory,
                         config: repository.config,
                     }, null, 2)}\n`);
                 }
-                else {
+                else if (repository.hasConfig) {
                     stdout(`${repository.configPath}\n`);
                 }
+                else {
+                    stdout(`defaults (${repository.rootDirectory})\n`);
+                }
                 return 0;
             }
             const result = await diagnoseRepository(repository);
@@ -522,7 +813,7 @@ export async function runCli(args, context = {}) {
             });
             stdout(values.json
                 ? `${JSON.stringify(result, null, 2)}\n`
-                : `Synced ${result.migrations.length} migrations and generated views\n`);
+                : `Synced ${result.migrations.length + result.documentMigrations.length} migrations and generated views\n`);
             return 0;
         }
         if (command === 'snapshot') {
@@ -605,35 +896,38 @@ export async function runCli(args, context = {}) {
                 const parsed = parseArgs({
                     args: subcommandArgs,
                     allowPositionals: true,
-                    options: {
-                        ...commonOptionDefinitions,
-                        title: { type: 'string' },
-                        status: { type: 'string' },
-                        label: { type: 'string', multiple: true },
-                        related: { type: 'string', multiple: true },
-                        body: { type: 'string' },
-                    },
+                    options: { ...metadataOptionDefinitions, ...commonOptionDefinitions },
                 });
                 const [rawType] = requirePositionals(parsed.positionals, 1, 'exactly one document type');
-                const values = parseSchema(z.strictObject({
-                    title: TrimmedStringSchema,
-                    status: DocumentStatusSchema.optional(),
-                    label: StringListSchema.optional(),
-                    related: StringListSchema.optional(),
-                    body: z.string().optional(),
-                    cwd: CwdSchema,
-                    json: JsonSchema,
-                }), parsed.values, 'document create options');
+                const values = parseSchema(DocumentCreateValuesSchema, parsed.values, 'document create options');
                 const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
                 const record = await createDocument(repository, {
                     type: normalizeDocumentKind(parseSchema(z.string(), rawType, 'document type')),
                     title: values.title,
                     ...(values.status ? { status: values.status } : {}),
+                    ...(values.priority ? { priority: values.priority } : {}),
+                    ...(values.order !== undefined ? { order: values.order } : {}),
                     ...(values.label ? { labels: values.label } : {}),
+                    ...(values['depends-on'] ? { dependsOn: values['depends-on'] } : {}),
+                    ...(values.file ? { files: normalizeMutationPaths(repository, values.file) } : {}),
+                    ...(values.owner ? { owner: values.owner } : {}),
+                    ...(values.assignee ? { assignees: values.assignee } : {}),
+                    ...(values.reviewer ? { reviewers: values.reviewer } : {}),
+                    ...(values.team ? { team: values.team } : {}),
+                    ...(values.estimate !== undefined ? { estimate: values.estimate } : {}),
+                    ...(values.effort !== undefined ? { effort: values.effort } : {}),
+                    ...(values.risk ? { risk: values.risk } : {}),
+                    ...(values['due-date'] ? { dueDate: values['due-date'] } : {}),
                     ...(values.related ? { related: values.related } : {}),
+                    ...(values.duplicate ? { duplicates: values.duplicate } : {}),
+                    ...(values.parent ? { parent: values.parent } : {}),
+                    ...(values.directory
+                        ? { directories: normalizeMutationPaths(repository, values.directory) }
+                        : {}),
+                    ...(values.project ? { projects: values.project } : {}),
                     ...(values.body !== undefined ? { body: values.body } : {}),
-                });
-                stdout(values.json ? `${JSON.stringify(record, null, 2)}\n` : `${record.document.metadata.id}\n`);
+                }, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
                 return 0;
             }
             if (subcommand === 'import') {
@@ -668,33 +962,206 @@ export async function runCli(args, context = {}) {
                 const parsed = parseArgs({
                     args: subcommandArgs,
                     allowPositionals: true,
-                    options: commonOptionDefinitions,
+                    options: {
+                        cwd: { type: 'string' },
+                        json: { type: 'boolean' },
+                        status: { type: 'string', multiple: true },
+                        priority: { type: 'string', multiple: true },
+                        label: { type: 'string', multiple: true },
+                        owner: { type: 'string', multiple: true },
+                        assignee: { type: 'string', multiple: true },
+                        reviewer: { type: 'string', multiple: true },
+                        team: { type: 'string', multiple: true },
+                        risk: { type: 'string', multiple: true },
+                        project: { type: 'string', multiple: true },
+                        'depends-on': { type: 'string' },
+                        related: { type: 'string' },
+                        duplicate: { type: 'string' },
+                        parent: { type: 'string' },
+                        file: { type: 'string', multiple: true },
+                        directory: { type: 'string', multiple: true },
+                        'estimate-min': { type: 'string' },
+                        'estimate-max': { type: 'string' },
+                        'effort-min': { type: 'string' },
+                        'effort-max': { type: 'string' },
+                        'due-before': { type: 'string' },
+                        'due-after': { type: 'string' },
+                        'created-before': { type: 'string' },
+                        'created-after': { type: 'string' },
+                        'updated-before': { type: 'string' },
+                        'updated-after': { type: 'string' },
+                        search: { type: 'string' },
+                        sort: { type: 'string' },
+                        direction: { type: 'string' },
+                        impact: { type: 'boolean' },
+                        'include-derived': { type: 'boolean' },
+                    },
                 });
                 if (parsed.positionals.length > 1)
                     throw new CliUsageError('Expected at most one document type');
-                const values = parseSchema(CommonValuesSchema, parsed.values, 'document list options');
+                const values = parseSchema(DocumentListValuesSchema, parsed.values, 'document list options');
+                const typeFilter = parsed.positionals[0]
+                    ? normalizeDocumentKind(parsed.positionals[0])
+                    : undefined;
+                const query = parseSchema(DocumentQuerySchema, {
+                    ...(typeFilter ? { types: [typeFilter] } : {}),
+                    ...(values.status ? { statuses: values.status } : {}),
+                    ...(values.priority ? { priorities: values.priority } : {}),
+                    ...(values.label ? { labels: values.label } : {}),
+                    ...(values.owner ? { owners: values.owner } : {}),
+                    ...(values.assignee ? { assignees: values.assignee } : {}),
+                    ...(values.reviewer ? { reviewers: values.reviewer } : {}),
+                    ...(values.team ? { teams: values.team } : {}),
+                    ...(values.risk ? { risks: values.risk } : {}),
+                    ...(values.project ? { projects: values.project } : {}),
+                    ...(values['depends-on'] ? { dependsOn: values['depends-on'] } : {}),
+                    ...(values.related ? { related: values.related } : {}),
+                    ...(values.duplicate ? { duplicate: values.duplicate } : {}),
+                    ...(values.parent ? { parent: values.parent } : {}),
+                    ...(values.file ? { files: values.file } : {}),
+                    ...(values.directory ? { directories: values.directory } : {}),
+                    ...(values['estimate-min'] !== undefined
+                        ? { estimateMin: values['estimate-min'] }
+                        : {}),
+                    ...(values['estimate-max'] !== undefined
+                        ? { estimateMax: values['estimate-max'] }
+                        : {}),
+                    ...(values['effort-min'] !== undefined ? { effortMin: values['effort-min'] } : {}),
+                    ...(values['effort-max'] !== undefined ? { effortMax: values['effort-max'] } : {}),
+                    ...(values['due-before'] ? { dueBefore: values['due-before'] } : {}),
+                    ...(values['due-after'] ? { dueAfter: values['due-after'] } : {}),
+                    ...(values['created-before'] ? { createdBefore: values['created-before'] } : {}),
+                    ...(values['created-after'] ? { createdAfter: values['created-after'] } : {}),
+                    ...(values['updated-before'] ? { updatedBefore: values['updated-before'] } : {}),
+                    ...(values['updated-after'] ? { updatedAfter: values['updated-after'] } : {}),
+                    ...(values.search !== undefined ? { text: values.search } : {}),
+                    ...(values.sort ? { sortBy: values.sort } : {}),
+                    ...(values.direction ? { direction: values.direction } : {}),
+                    ...(values.impact ? { impact: true } : {}),
+                }, 'document list query');
                 const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
-                const records = await listDocuments(repository, parsed.positionals[0] ? normalizeDocumentKind(parsed.positionals[0]) : undefined);
-                if (values.json)
-                    stdout(`${JSON.stringify(records, null, 2)}\n`);
-                else
-                    for (const record of records)
-                        stdout(`${record.document.metadata.id}\t${record.document.metadata.type}\t${record.document.metadata.status}\t${record.document.metadata.title}\n`);
+                const result = await queryDocuments(repository, query);
+                const derivedGraph = values['include-derived']
+                    ? buildDocumentGraph(await listDocuments(repository))
+                    : undefined;
+                const serialize = (record) => documentRecordJson(record, derivedGraph?.derive(record.document.metadata.id));
+                if (values.json) {
+                    stdout(`${JSON.stringify(values.impact
+                        ? {
+                            direct: result.direct.map(serialize),
+                            impacted: result.impacted.map(serialize),
+                        }
+                        : result.direct.map(serialize), null, 2)}\n`);
+                }
+                else {
+                    for (const record of result.direct) {
+                        stdout(`${values.impact ? 'direct\t' : ''}${record.document.metadata.id}\t${record.document.metadata.type}\t${record.document.metadata.status}\t${record.document.metadata.title}\n`);
+                    }
+                    for (const record of result.impacted) {
+                        stdout(`impact\t${record.document.metadata.id}\t${record.document.metadata.type}\t${record.document.metadata.status}\t${record.document.metadata.title}\n`);
+                    }
+                }
                 return 0;
             }
             if (subcommand === 'show') {
                 const parsed = parseArgs({
                     args: subcommandArgs,
                     allowPositionals: true,
-                    options: { ...commonOptionDefinitions, type: { type: 'string' } },
+                    options: {
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                        'include-derived': { type: 'boolean' },
+                    },
                 });
                 const [id] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
-                const values = parseSchema(z.strictObject({ ...CommonValuesSchema.shape, type: TrimmedStringSchema.optional() }), parsed.values, 'document show options');
+                const values = parseSchema(z.strictObject({
+                    ...CommonValuesSchema.shape,
+                    type: TrimmedStringSchema.optional(),
+                    'include-derived': z.boolean().optional(),
+                }), parsed.values, 'document show options');
                 const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
-                const record = await readDocument(repository, parseSchema(z.string(), id, 'document ID'), values.type ? normalizeDocumentKind(values.type) : undefined);
-                stdout(values.json
-                    ? `${JSON.stringify(record, null, 2)}\n`
-                    : serializeDocumentFile(record.document));
+                const validatedId = parseSchema(DocumentIdSchema, id, 'document ID');
+                const record = await readDocument(repository, validatedId, values.type ? normalizeDocumentKind(values.type) : undefined);
+                if (values.json) {
+                    const derived = values['include-derived']
+                        ? buildDocumentGraph(await listDocuments(repository)).derive(validatedId)
+                        : undefined;
+                    stdout(`${JSON.stringify({
+                        relativePath: record.relativePath,
+                        metadata: record.document.metadata,
+                        body: record.document.body,
+                        ...(derived ? { derived } : {}),
+                    }, null, 2)}\n`);
+                }
+                else {
+                    stdout(serializeDocumentFile(record.document));
+                }
+                return 0;
+            }
+            if (subcommand === 'update') {
+                const clearDefinitions = Object.fromEntries(UPDATE_CLEAR_PAIRS.map(([, clear]) => [clear, { type: 'boolean' }]));
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...metadataOptionDefinitions,
+                        ...clearDefinitions,
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                    },
+                });
+                const [documentId] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const values = parseSchema(DocumentUpdateValuesSchema, parsed.values, 'document update options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await updateDocument(repository, validatedDocumentId, documentUpdateInputFromValues(repository, values), values.type ? normalizeDocumentKind(values.type) : undefined, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
+                return 0;
+            }
+            if (subcommand === 'status') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: { ...commonOptionDefinitions, type: { type: 'string' } },
+                });
+                const [documentId, status] = requirePositionals(parsed.positionals, 2, 'a document ID and status');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const validatedStatus = parseSchema(DocumentStatusSchema, status, 'document status');
+                const values = parseSchema(z.strictObject({ ...CommonValuesSchema.shape, type: TrimmedStringSchema.optional() }), parsed.values, 'document status options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await updateDocument(repository, validatedDocumentId, { status: validatedStatus }, values.type ? normalizeDocumentKind(values.type) : undefined, { onWarning });
+                writeDocumentRecord(record, values.json, stdout);
+                return 0;
+            }
+            if (subcommand === 'delete') {
+                const parsed = parseArgs({
+                    args: subcommandArgs,
+                    allowPositionals: true,
+                    options: {
+                        ...commonOptionDefinitions,
+                        type: { type: 'string' },
+                        'remove-dependencies': { type: 'boolean' },
+                    },
+                });
+                const [documentId] = requirePositionals(parsed.positionals, 1, 'exactly one document ID');
+                const validatedDocumentId = parseSchema(DocumentIdSchema, documentId, 'document ID');
+                const values = parseSchema(z.strictObject({
+                    cwd: CwdSchema,
+                    json: JsonSchema,
+                    type: TrimmedStringSchema.optional(),
+                    'remove-dependencies': z.boolean().optional(),
+                }), parsed.values, 'document delete options');
+                const repository = await discoverRepository(resolveCommandCwd(cwd, values.cwd));
+                const record = await deleteDocument(repository, validatedDocumentId, values.type ? normalizeDocumentKind(values.type) : undefined, {
+                    removeDependencies: values['remove-dependencies'],
+                    onWarning,
+                });
+                if (values.json) {
+                    stdout(`${JSON.stringify({ deleted: true, ...documentRecordJson(record) }, null, 2)}\n`);
+                }
+                else {
+                    stdout(`${validatedDocumentId}\n`);
+                }
                 return 0;
             }
             throw new CliUsageError(`Unknown document command "${subcommand ?? ''}"`);