@eightstate/escli 0.5.0 → 0.7.1

package/dist/commands/notion/upload/attach.js

@@ -0,0 +1,105 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { writeStdout } from '../../../io/io.js';
+import { proxy } from '../../../services/notion.js';
+import { attachUploadedFiles, createdBlockId, emitNotionFailure, emitNotionSuccess, emitRaw, fileUploadErrors, FileUploadAttachReceiptSchema, nextForTarget, normalizeUpload, parseAttachTarget, rawFlag, renderAttachReceipt, requireUploaded, targetLabel, } from '../../../lib/notion/upload/shared.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../../../lib/escli-error.js';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+export { FileUploadAttachReceiptSchema as NotionUploadAttachDataSchema };
+export default class NotionUploadAttach extends BaseCommand {
+    static errors = fileUploadErrors;
+    static summary = 'Attach existing Notion file_upload ids';
+    static description = 'Validates existing file_upload ids and attaches them to a block, page files property, page cover, or page icon.';
+    static examples = [
+        '<%= config.bin %> notion file-upload attach fu_4383 --attach-to block:blk_6c42 --as pdf',
+        '<%= config.bin %> notion file-upload attach fu_1 fu_2 --attach property --page pg_123 --property Attachments',
+    ];
+    static aliases = ['notion upload attach'];
+    static flags = {
+        name: Flags.string({ description: 'Display name. Allowed only with one file_upload id.' }),
+        'attach-to': Flags.string({ description: 'Compact target: block:<id>, property:<page-id>:<property>, cover:<page-id>, or icon:<page-id>.' }),
+        attach: Flags.option({ description: 'Attachment target kind.', options: ['block', 'property', 'page'] })(),
+        parent: Flags.string({ description: 'Block/page id for block attachment.' }),
+        as: Flags.option({ description: 'Block attachment type.', options: ['file', 'image', 'pdf', 'video', 'audio'], default: 'file' })(),
+        page: Flags.string({ description: 'Page id for property/page attachment.' }),
+        property: Flags.string({ description: 'Files property name or id.' }),
+        slot: Flags.option({ description: 'Page file slot.', options: ['cover', 'icon'] })(),
+        caption: Flags.string({ description: 'Caption for block attachments.' }),
+        'replace-all': Flags.boolean({ description: 'Replace property files instead of appending.', default: false }),
+        yes: Flags.boolean({ description: 'Accept non-interactive replacement confirmations.', default: false }),
+        raw: rawFlag,
+    };
+    static args = {
+        'file-upload-id': Args.string({ description: 'Notion file_upload id(s).', required: true, multiple: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = false;
+        try {
+            const { data, raw } = await this.perform();
+            if (raw)
+                return;
+            json = data.json;
+            if (json)
+                await emitNotionSuccess(this.id ?? 'notion file-upload attach', this.config.version, data.receipt, Date.now() - start);
+            else
+                await writeStdout(`${renderAttachReceipt(data.receipt)}\n`);
+        }
+        catch (error) {
+            await emitNotionFailure(this.id ?? 'notion file-upload attach', this.config.version, error, Date.now() - start, json);
+        }
+    }
+    async execute() {
+        return (await this.perform()).data.receipt;
+    }
+    async perform() {
+        const { args, flags } = await this.parse(NotionUploadAttach);
+        const ids = args['file-upload-id'];
+        if (flags.name && ids.length !== 1)
+            throw new EscliError('--name is only valid with one file_upload id', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        const target = parseAttachTarget(flags);
+        if (target.kind === 'none')
+            throw new EscliError('--attach or --attach-to is required', { code: ErrorCode.UsageRequired, exitCode: ExitCodes.Usage });
+        if (target.kind === 'property' && target.replace_all && !flags.yes)
+            throw new EscliError('replace-all would overwrite existing files property; rerun with --yes', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        if (target.kind === 'page' && ids.length !== 1)
+            throw new EscliError('page cover/icon accepts exactly one file_upload id', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        const rawChain = [];
+        const uploads = [];
+        for (const id of ids) {
+            const result = await proxy('GET', `/v1/file_uploads/${encodeURIComponent(id)}`);
+            rawChain.push(result.raw);
+            const upload = normalizeUpload(result.data);
+            upload.id ??= id;
+            requireUploaded(upload);
+            uploads.push({ id, name: flags.name ?? upload.name ?? upload.filename });
+        }
+        const attached = await attachUploadedFiles(target, uploads);
+        if (attached)
+            rawChain.push(attached.raw);
+        const blockId = target.kind === 'block' ? createdBlockId(attached?.data) : null;
+        if (flags.raw) {
+            await emitRaw(rawChain);
+            return { data: { receipt: { operation: 'file-upload.attach', attached: ids.length, target: targetLabel(target) ?? '', created_block_id: blockId, file_upload_ids: ids, file_upload_id: ids[0], next: null }, json: Boolean(flags.json) }, raw: true };
+        }
+        const receipt = FileUploadAttachReceiptSchema.parse({
+            operation: 'file-upload.attach',
+            attached: ids.length,
+            target: targetLabel(target),
+            created_block_id: blockId,
+            file_upload_ids: ids,
+            file_upload_id: ids[0],
+            next: nextForTarget(target, blockId),
+        });
+        return { data: { receipt, json: Boolean(flags.json) }, raw: false };
+    }
+}
+//# sourceMappingURL=attach.js.map

package/dist/commands/notion/upload/index.js

@@ -0,0 +1,129 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { writeStdout, writeStderr } from '../../../io/io.js';
+import { notionFileUploadComplete, notionFileUploadCreate, notionFileUploadSend } from '../../../services/notion.js';
+import { attachUploadedFiles, decideMode, emitRaw, fileUploadErrors, fileUploadId, FileUploadReceiptSchema, emitNotionFailure, emitNotionSuccess, nextForTarget, parseAttachTarget, rawFlag, readLocalFile, renderUploadReceipt, targetLabel, } from '../../../lib/notion/upload/shared.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../../../lib/escli-error.js';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+const MIB = 1024 * 1024;
+export { FileUploadReceiptSchema as NotionUploadDataSchema };
+export default class NotionUpload extends BaseCommand {
+    static errors = fileUploadErrors;
+    static summary = 'Upload local files to Notion file_upload storage';
+    static description = 'Creates Notion file_upload objects, sends bytes, completes multipart uploads, and optionally attaches them.';
+    static examples = [
+        '<%= config.bin %> notion file-upload upload ./diagram.png',
+        '<%= config.bin %> notion file-upload upload ./demo.mov --attach-to block:blk_123 --as video',
+        '<%= config.bin %> notion file-upload upload ./diagram.png --attach property --page pg_123 --property Attachments',
+    ];
+    static aliases = ['notion upload'];
+    static flags = {
+        mode: Flags.option({ description: 'Upload mode.', options: ['auto', 'single', 'multi'], default: 'auto' })(),
+        name: Flags.string({ description: 'Display name. Allowed only with one file.' }),
+        'part-size-mib': Flags.integer({ description: 'Multipart part size in MiB.', default: 10 }),
+        'parallel-parts': Flags.integer({ description: 'Multipart parallelism hint.', default: 2 }),
+        'attach-to': Flags.string({ description: 'Compact target: block:<id>, property:<page-id>:<property>, cover:<page-id>, or icon:<page-id>.' }),
+        attach: Flags.option({ description: 'Attachment target kind.', options: ['block', 'property', 'page'] })(),
+        parent: Flags.string({ description: 'Block/page id for block attachment.' }),
+        as: Flags.option({ description: 'Block attachment type.', options: ['file', 'image', 'pdf', 'video', 'audio'], default: 'file' })(),
+        page: Flags.string({ description: 'Page id for property/page attachment.' }),
+        property: Flags.string({ description: 'Files property name or id.' }),
+        slot: Flags.option({ description: 'Page file slot.', options: ['cover', 'icon'] })(),
+        caption: Flags.string({ description: 'Caption for block attachments.' }),
+        'replace-all': Flags.boolean({ description: 'Replace property files instead of appending.', default: false }),
+        yes: Flags.boolean({ description: 'Accept non-interactive replacement / large batch confirmations.', default: false }),
+        raw: rawFlag,
+    };
+    static args = {
+        path: Args.string({ description: 'Local file path(s).', required: true, multiple: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = false;
+        try {
+            const { data, raw } = await this.perform();
+            if (raw)
+                return;
+            json = data.json;
+            if (json)
+                await emitNotionSuccess(this.id ?? 'notion file-upload upload', this.config.version, data.receipt, Date.now() - start);
+            else {
+                await writeStdout(`${renderUploadReceipt(data.receipt)}\n`);
+                if (!data.quiet && data.unattachedWarning)
+                    await writeStderr(`${data.unattachedWarning}\n`);
+            }
+        }
+        catch (error) {
+            await emitNotionFailure(this.id ?? 'notion file-upload upload', this.config.version, error, Date.now() - start, json);
+        }
+    }
+    async execute() {
+        return (await this.perform()).data.receipt;
+    }
+    async perform() {
+        const { args, flags } = await this.parse(NotionUpload);
+        const paths = args.path;
+        if (flags.name && paths.length !== 1)
+            throw new EscliError('--name is only valid with one file', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        if (flags['part-size-mib'] < 5 || flags['part-size-mib'] > 20)
+            throw new EscliError('--part-size-mib must be between 5 and 20', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        if (flags['parallel-parts'] < 1 || flags['parallel-parts'] > 3)
+            throw new EscliError('--parallel-parts must be between 1 and 3', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        const target = parseAttachTarget(flags);
+        if (target.kind === 'property' && target.replace_all && !flags.yes)
+            throw new EscliError('replace-all would overwrite existing files property; rerun with --yes', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        if (target.kind === 'page' && paths.length !== 1)
+            throw new EscliError('page cover/icon accepts exactly one file_upload id', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        const files = await Promise.all(paths.map((path) => readLocalFile(path)));
+        const uploaded = [];
+        const rawChain = [];
+        for (const file of files) {
+            const name = flags.name ?? file.name;
+            const mode = decideMode(file.size, flags.mode);
+            const parts = mode === 'multi_part' ? Math.max(1, Math.ceil(file.size / (flags['part-size-mib'] * MIB))) : undefined;
+            const created = await notionFileUploadCreate({ mode, filename: name, name, ...(parts ? { number_of_parts: parts } : {}) });
+            rawChain.push(created.raw);
+            const id = fileUploadId(created.data);
+            if (mode === 'single_part') {
+                const sent = await notionFileUploadSend(id, { file: file.bytes, filename: name });
+                rawChain.push(sent.raw);
+            }
+            else {
+                for (let index = 0; index < (parts ?? 1); index += 1) {
+                    const start = index * flags['part-size-mib'] * MIB;
+                    const end = Math.min(file.bytes.length, start + flags['part-size-mib'] * MIB);
+                    const sent = await notionFileUploadSend(id, { file: file.bytes.subarray(start, end), filename: name });
+                    rawChain.push(sent.raw);
+                }
+                const completed = await notionFileUploadComplete(id);
+                rawChain.push(completed.raw);
+            }
+            uploaded.push({ name, file_upload_id: id, status: 'uploaded', mode, size_bytes: file.size, parts, persistent: target.kind !== 'none' });
+        }
+        const attachResult = await attachUploadedFiles(target, uploaded.map((file) => ({ id: file.file_upload_id, name: file.name })));
+        if (attachResult)
+            rawChain.push(attachResult.raw);
+        if (flags.raw) {
+            await emitRaw(rawChain);
+            return { data: { receipt: { operation: 'file-upload.upload', uploaded: uploaded.length, attached: target.kind === 'none' ? 0 : uploaded.length, target: targetLabel(target), files: uploaded, next: null }, json: Boolean(flags.json), quiet: flags.quiet }, raw: true };
+        }
+        const receipt = FileUploadReceiptSchema.parse({
+            operation: 'file-upload.upload',
+            uploaded: uploaded.length,
+            attached: target.kind === 'none' ? 0 : uploaded.length,
+            target: targetLabel(target),
+            files: uploaded,
+            next: target.kind === 'none' ? `escli notion file-upload attach ${uploaded.map((file) => file.file_upload_id).join(' ')} --attach ...` : nextForTarget(target, null),
+        });
+        return { data: { receipt, json: Boolean(flags.json), quiet: flags.quiet, unattachedWarning: target.kind === 'none' ? `unattached uploads expire unless attached: escli notion file-upload attach ${uploaded.map((file) => file.file_upload_id).join(' ')} --attach ...` : undefined }, raw: false };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/notion/upload/list.js

@@ -0,0 +1,78 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../../base-command.js';
+import { writeStdout } from '../../../io/io.js';
+import { proxy } from '../../../services/notion.js';
+import { emitNotionFailure, emitNotionSuccess, emitRaw, fileUploadErrors, FileUploadListReceiptSchema, listResults, rawFlag, renderListReceipt, uploadState, } from '../../../lib/notion/upload/shared.js';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../../../lib/escli-error.js';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+export { FileUploadListReceiptSchema as NotionUploadListDataSchema };
+export default class NotionUploadList extends BaseCommand {
+    static errors = fileUploadErrors;
+    static summary = 'List recent Notion file_uploads';
+    static description = 'Emits one bounded recent page of bot-created Notion file uploads. This command is intentionally not paginated.';
+    static examples = ['<%= config.bin %> notion file-upload list', '<%= config.bin %> notion file-upload list --status uploaded --page-size 20'];
+    static aliases = ['notion upload list', 'notion file-upload ls'];
+    static flags = {
+        status: Flags.option({ description: 'Filter by upload status.', options: ['pending', 'uploaded', 'expired', 'failed'] })(),
+        'created-after': Flags.string({ description: 'Filter to uploads created after an ISO-8601 timestamp.' }),
+        'page-size': Flags.integer({ description: 'Bounded recent page size.', default: 20 }),
+        raw: rawFlag,
+    };
+    static args = {};
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = false;
+        try {
+            const { data, raw } = await this.perform();
+            if (raw)
+                return;
+            json = data.json;
+            if (json)
+                await emitNotionSuccess(this.id ?? 'notion file-upload list', this.config.version, data.receipt, Date.now() - start);
+            else
+                await writeStdout(`${renderListReceipt(data.receipt)}\n`);
+        }
+        catch (error) {
+            await emitNotionFailure(this.id ?? 'notion file-upload list', this.config.version, error, Date.now() - start, json);
+        }
+    }
+    async execute() {
+        return (await this.perform()).data.receipt;
+    }
+    async perform() {
+        const { flags } = await this.parse(NotionUploadList);
+        if (flags['page-size'] < 1 || flags['page-size'] > 100)
+            throw new EscliError('--page-size must be between 1 and 100', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        const result = await proxy('GET', '/v1/file_uploads', { query: { status: flags.status, created_after: flags['created-after'], page_size: flags['page-size'] } });
+        if (flags.raw) {
+            await emitRaw(result.raw);
+            return { data: { receipt: buildReceipt(result.data, flags), json: Boolean(flags.json) }, raw: true };
+        }
+        const receipt = FileUploadListReceiptSchema.parse(buildReceipt(result.data, flags));
+        return { data: { receipt, json: Boolean(flags.json) }, raw: false };
+    }
+}
+function buildReceipt(raw, flags) {
+    const uploads = listResults(raw).map((upload) => ({ id: upload.id ?? '', name: upload.name ?? upload.filename, status: upload.status ?? 'unknown', expiry_time: upload.expiry_time, state: uploadState(upload) }));
+    return {
+        operation: 'file-upload.list',
+        count: uploads.length,
+        filter: { status: flags.status, created_after: flags['created-after'], page_size: flags['page-size'] },
+        counts_on_page: {
+            attach_now: uploads.filter((upload) => upload.state === 'attach_now').length,
+            persistent: uploads.filter((upload) => upload.state === 'persistent').length,
+            pending: uploads.filter((upload) => upload.state === 'pending').length,
+            dead: uploads.filter((upload) => upload.state === 'dead').length,
+        },
+        uploads,
+    };
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/notion/upload/status.js

@@ -0,0 +1,76 @@
+import { Args } from '@oclif/core';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+import { BaseCommand } from '../../../base-command.js';
+import { writeStdout } from '../../../io/io.js';
+import { proxy } from '../../../services/notion.js';
+import { emitNotionFailure, emitNotionSuccess, emitRaw, fileUploadErrors, FileUploadStatusReceiptSchema, normalizeUpload, rawFlag, renderStatusReceipt, uploadState, } from '../../../lib/notion/upload/shared.js';
+export { FileUploadStatusReceiptSchema as NotionUploadStatusDataSchema };
+export default class NotionUploadStatus extends BaseCommand {
+    static errors = fileUploadErrors;
+    static summary = 'Check Notion file_upload status';
+    static description = 'Checks whether supplied file_upload ids are attachable, persistent, pending, or dead.';
+    static examples = ['<%= config.bin %> notion file-upload status fu_9bb1 fu_4383', '<%= config.bin %> --json notion file-upload status fu_9bb1'];
+    static aliases = ['notion upload status'];
+    static flags = { raw: rawFlag };
+    static args = {
+        'file-upload-id': Args.string({ description: 'Notion file_upload id(s).', required: true, multiple: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        const start = Date.now();
+        let json = false;
+        try {
+            const { data, raw } = await this.perform();
+            if (raw)
+                return;
+            json = data.json;
+            if (json)
+                await emitNotionSuccess(this.id ?? 'notion file-upload status', this.config.version, data.receipt, Date.now() - start);
+            else
+                await writeStdout(`${renderStatusReceipt(data.receipt)}\n`);
+        }
+        catch (error) {
+            await emitNotionFailure(this.id ?? 'notion file-upload status', this.config.version, error, Date.now() - start, json);
+        }
+    }
+    async execute() {
+        return (await this.perform()).data.receipt;
+    }
+    async perform() {
+        const { args, flags } = await this.parse(NotionUploadStatus);
+        const ids = args['file-upload-id'];
+        const rawChain = [];
+        const uploads = [];
+        for (const id of ids) {
+            const result = await proxy('GET', `/v1/file_uploads/${encodeURIComponent(id)}`);
+            rawChain.push(result.raw);
+            const upload = normalizeUpload(result.data);
+            uploads.push({ id: upload.id ?? id, name: upload.name ?? upload.filename, status: upload.status ?? 'unknown', expiry_time: upload.expiry_time, state: uploadState(upload) });
+        }
+        if (flags.raw) {
+            await emitRaw(rawChain);
+            return { data: { receipt: buildReceipt(uploads), json: Boolean(flags.json) }, raw: true };
+        }
+        const receipt = FileUploadStatusReceiptSchema.parse(buildReceipt(uploads));
+        return { data: { receipt, json: Boolean(flags.json) }, raw: false };
+    }
+}
+function buildReceipt(uploads) {
+    return {
+        operation: 'file-upload.status',
+        checked: uploads.length,
+        states: {
+            attach_now: uploads.filter((upload) => upload.state === 'attach_now').length,
+            persistent: uploads.filter((upload) => upload.state === 'persistent').length,
+            pending: uploads.filter((upload) => upload.state === 'pending').length,
+            dead: uploads.filter((upload) => upload.state === 'dead').length,
+        },
+        uploads,
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/notion/view/create.js

@@ -0,0 +1,78 @@
+import { Args, Flags } from '@oclif/core';
+import { hasManifestFlag } from '../../../lib/notion/manifest-pass.js';
+import { BaseCommand } from '../../../base-command.js';
+import { writeStdout } from '../../../io/io.js';
+import { proxy } from '../../../services/notion.js';
+import { dryRunData, emitRawOrReturn, maybeDryRunWarning, normalizeViewCreateResponse, notionCreateErrors, parseOptionalJsonInput, parsePosition, parseSortFlags, parseViewType, renderViewCreate, viewLocation, } from '../db/create.js';
+export default class NotionViewCreate extends BaseCommand {
+    static errors = notionCreateErrors;
+    static summary = 'Create a Notion database view';
+    static description = 'Create one database view over an existing data source, placed in a database, dashboard, or linked page location.';
+    static examples = [
+        '<%= config.bin %> notion view create "Renewals this quarter" --data-source 74b1dd01-5e4d-4f64-a67e-e60ce75bb901 --in-db 362e7f31-7d53-4f6a-a0f6-7a7a7b68b0dc --type table --filter renewals-q.filter.json --sort Renewal:asc',
+        '<%= config.bin %> notion view create "Renewals this quarter" --data-source 74b1dd01-5e4d-4f64-a67e-e60ce75bb901 --in-db 362e7f31-7d53-4f6a-a0f6-7a7a7b68b0dc --type table --dry-run',
+        '<%= config.bin %> --json notion view create "Renewals this quarter" --data-source 74b1dd01-5e4d-4f64-a67e-e60ce75bb901 --in-db 362e7f31-7d53-4f6a-a0f6-7a7a7b68b0dc --type table',
+    ];
+    static aliases = ['notion views create', 'n view create', 'n views create'];
+    static flags = {
+        'data-source': Flags.string({ description: 'Data source ID.', required: true }),
+        'in-db': Flags.string({ description: 'Place as a top-level database tab.' }),
+        'in-dashboard': Flags.string({ description: 'Place as a dashboard widget under this view ID.' }),
+        'linked-on': Flags.string({ description: 'Place as a linked database on this page ID.' }),
+        type: Flags.string({ description: 'View type.', required: true, options: ['table', 'board', 'list', 'calendar', 'timeline', 'gallery', 'form', 'chart', 'map'] }),
+        filter: Flags.string({ description: 'Filter JSON path or inline JSON.' }),
+        sort: Flags.string({ description: 'Sort as <property:asc|property:desc>.', multiple: true }),
+        config: Flags.string({ description: 'Configuration JSON path or inline JSON.' }),
+        position: Flags.string({ description: 'View position: start, end, or after:<view_id>.' }),
+        raw: Flags.boolean({ description: 'Emit verbatim Notion response body.', default: false }),
+        'dry-run': Flags.boolean({ description: 'Validate inputs and print the create payload without writing to Notion.', default: false }),
+    };
+    static args = {
+        name: Args.string({ description: 'View name.', required: true }),
+    };
+    static enableJsonFlag = true;
+    static strict = true;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        if (this.argv.includes('--raw')) {
+            await this.execute();
+            return;
+        }
+        await super.run();
+    }
+    async execute() {
+        const { args, flags } = await this.parse(NotionViewCreate);
+        const request = {
+            name: args.name,
+            data_source_id: flags['data-source'],
+            type: parseViewType(flags.type),
+            location: viewLocation(flags),
+            filter: await parseOptionalJsonInput(flags.filter, 'filter'),
+            sorts: parseSortFlags(flags.sort),
+            config: await parseOptionalJsonInput(flags.config, 'config'),
+            position: parsePosition(flags.position),
+        };
+        if (flags['dry-run']) {
+            await maybeDryRunWarning(flags, 'view create');
+            const data = { ...dryRunData('view', request), query_shape: { sorts: [] } };
+            if (!flags.json) {
+                await writeStdout(`${renderViewCreate(data)}\n`);
+                this.humanOutputHandled = true;
+            }
+            return data;
+        }
+        const result = await proxy('POST', '/v1/views', { body: request });
+        const payload = await emitRawOrReturn(result, flags.raw);
+        const data = normalizeViewCreateResponse(payload, request);
+        if (!flags.json && !flags.raw) {
+            await writeStdout(`${renderViewCreate(data)}\n`);
+            this.humanOutputHandled = true;
+        }
+        return { ...data, raw: result.raw };
+    }
+}
+export { renderViewCreate };
+//# sourceMappingURL=create.js.map

package/dist/commands/notion/whoami.js

@@ -0,0 +1,96 @@
+import { Flags } from '@oclif/core';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { BaseCommand } from '../../base-command.js';
+import { renderKv } from '../../io/render-kv.js';
+import { writeStdout } from '../../io/io.js';
+import { notionCommentsList, notionFetchPage, proxy, whoami } from '../../services/notion.js';
+import { hasManifestFlag } from '../../lib/notion/manifest-pass.js';
+import { formatBot, formatWhoamiCapabilities, normalizeRecord, recordValue, runNotionCommand, stringValue, successEnvelope, validateVerify, } from './enroll.js';
+const VERIFY_OPTIONS = ['identity', 'read', 'comments', 'users', 'all'];
+export default class NotionWhoami extends BaseCommand {
+    static errors = [ErrorCode.UsageRequired, ErrorCode.UsageInvalid, ErrorCode.UsageUnknownFlag, ErrorCode.ValidationFailed, ErrorCode.AuthRequired, ErrorCode.NotionEnrollmentRequired, ErrorCode.NotionUnauthorized, ErrorCode.NotionRestricted, ErrorCode.NotionNotFound, ErrorCode.NotionRateLimited, ErrorCode.NotionValidation, ErrorCode.NotionConflict, ErrorCode.NotionTimeoutUncertain, ErrorCode.GateInvalidResponse, ErrorCode.NetworkError, ErrorCode.NetworkTimeout, ErrorCode.ServiceUnavailable, ErrorCode.ApiError, ErrorCode.Internal];
+    static summary = 'Show the enrolled Notion bot identity and readiness';
+    static description = 'Show which Notion bot/workspace this Clerk user is enrolled to use, plus non-mutating capability verification status.';
+    static examples = ['<%= config.bin %> notion whoami', '<%= config.bin %> notion whoami --probe-page 362e --verify all', '<%= config.bin %> --json notion whoami --verify identity'];
+    static aliases = [];
+    static flags = {
+        'probe-page': Flags.string({ description: 'Page/block ID or URL used for non-mutating read/comment probes.' }),
+        verify: Flags.string({ description: 'Verification depth.', options: [...VERIFY_OPTIONS], default: 'identity' }),
+        raw: Flags.boolean({ description: 'Emit verbatim ordered Notion response body chain.', default: false }),
+    };
+    static args = {};
+    static enableJsonFlag = true;
+    static strict = true;
+    outputHandled = false;
+    async run() {
+        if (hasManifestFlag(this.argv)) {
+            await super.run();
+            return;
+        }
+        await runNotionCommand(this);
+    }
+    async execute() {
+        const { flags } = await this.parse(NotionWhoami);
+        validateVerify(flags.verify, flags['probe-page']);
+        const result = await whoami();
+        const data = normalizeRecord(result.data);
+        const rawChain = [result.raw];
+        await runRequestedProbes(flags.verify, flags['probe-page'], rawChain);
+        if (flags.raw) {
+            await writeStdout(`${JSON.stringify(rawChain)}\n`);
+            this.outputHandled = true;
+            return data;
+        }
+        if (flags.json) {
+            await writeStdout(`${JSON.stringify(successEnvelope(data))}\n`);
+            this.outputHandled = true;
+            return data;
+        }
+        await writeStdout(`${renderWhoami(data)}\n`);
+        this.outputHandled = true;
+        return data;
+    }
+}
+export function renderWhoami(data) {
+    const identity = recordValue(data.notion_identity) ?? recordValue(data.identity) ?? recordValue(data.bot) ?? data;
+    const clerkUser = recordValue(data.clerk_user);
+    const custody = recordValue(data.custody);
+    const capabilities = recordValue(data.capabilities);
+    const rows = [
+        ['notion identity', stringValue(data.status) ?? 'ready'],
+        ['bot', formatWhoamiBot(identity)],
+        ['attribution', stringValue(identity.attribution) === 'bot' || !stringValue(identity.attribution) ? `edits appear as bot "${stringValue(identity.name) ?? 'unknown'}", not the human user` : String(identity.attribution)],
+        ['capabilities', formatWhoamiCapabilities(capabilities)],
+        ['custody', formatWhoamiCustody(custody, clerkUser, data)],
+        ['next', stringValue(data.next) ?? 'use --probe-page <id> --verify all before write/comment work'],
+    ];
+    return renderKv(rows);
+}
+function formatWhoamiBot(identity) {
+    const workspace = stringValue(identity.workspace_name);
+    const bot = formatBot(identity);
+    return workspace ? `${bot} in ${workspace}` : bot;
+}
+async function runRequestedProbes(verify, probePage, rawChain) {
+    if ((verify === 'read' || verify === 'all') && probePage) {
+        const readResult = await notionFetchPage(probePage);
+        rawChain.push(readResult.raw);
+    }
+    if ((verify === 'comments' || verify === 'all') && probePage) {
+        const commentsResult = await notionCommentsList(probePage);
+        rawChain.push(commentsResult.raw);
+    }
+    if (verify === 'users' || verify === 'all') {
+        const usersResult = await proxy('GET', '/v1/users');
+        rawChain.push(usersResult.raw);
+    }
+}
+function formatWhoamiCustody(custody, clerkUser, data) {
+    const clerkId = stringValue(clerkUser?.id) ?? stringValue(data.clerk_user_id);
+    if (clerkId)
+        return `server-side token for clerk ${clerkId}`;
+    if (custody && custody.stored === false)
+        return 'not enrolled';
+    return 'server-side token stored';
+}
+//# sourceMappingURL=whoami.js.map

package/dist/commands/research.js

@@ -16,6 +16,7 @@ export const ResearchOutputSchema = z.object({
 export const ResearchDataSchema = z.union([
     z.object({ processors: z.array(ResearchProcessorSchema), count: z.number().int().nonnegative() }),
     z.object({ run_id: z.string(), processor: z.string(), output: ResearchOutputSchema, path: z.string().optional() }),
+    z.object({ run_id: z.string(), processor: z.string(), status: z.string() }),
     z.object({ run_id: z.string(), status: z.string(), error: z.unknown().optional(), warnings: z.array(z.unknown()).optional() }),
     z.object({ run_id: z.string(), output: ResearchOutputSchema, path: z.string().optional() }),
 ]);
@@ -49,6 +50,8 @@ export default class Research extends BaseCommand {
         metadata: Flags.string({ description: 'Metadata as JSON or key=val,key=val.' }),
         'follow-up': Flags.string({ description: 'Follow up on a previous run.' }),
         'no-basis': Flags.boolean({ description: 'Exclude citations and reasoning from human/file output.', default: false }),
+        'max-wait': Flags.integer({ description: 'Max seconds to poll for completion (default: 7200, i.e. 2h). Per-request HTTP timeout is still --timeout.' }),
+        async: Flags.boolean({ description: 'Submit task and exit immediately with run_id; do not poll. Recover with --status / --result.', default: false }),
     };
     static args = {
         query: Args.string({ description: 'Research question or topic.', required: false, multiple: true }),
@@ -66,6 +69,12 @@ export default class Research extends BaseCommand {
         const query = args.query?.join(' ').trim() ?? '';
         if (!query)
             throw new EscliError('usage: escli research "query" -o output.md', { code: ErrorCode.UsageRequired, exitCode: ExitCodes.Usage });
+        if (flags.async && flags.output) {
+            throw new EscliError('--output requires a completed result; use `escli research --result <run_id> -o <path>` after the task completes.', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        }
+        if (typeof flags['max-wait'] === 'number' && flags['max-wait'] < 1) {
+            throw new EscliError('--max-wait must be >= 1; use --async to submit without polling.', { code: ErrorCode.UsageInvalid, exitCode: ExitCodes.Usage });
+        }
         if (!flags.quiet && !flags.json)
             await writeStderr(`  ▸ submitting task (processor=${flags.processor})...\n`);
         return runResearch({
@@ -86,6 +95,8 @@ export default class Research extends BaseCommand {
             noBasis: flags['no-basis'],
             quiet: flags.quiet || flags.json,
             timeoutSeconds: flags.timeout,
+            maxWaitSeconds: flags['max-wait'],
+            async: flags.async,
         });
     }
 }

package/dist/entry.js

@@ -7,11 +7,12 @@ import { buildErrorEnvelope, buildUsageError } from './lib/envelope.js';
 import { GLOBAL_SHORT_FLAGS, globalFlagTakesValue, isGlobalFlagToken } from './lib/globals.js';
 import { commandRegistry, commandsById } from './lib/registry.js';
 import { writeStdout } from './io/io.js';
+import packageJson from '../package.json' with { type: 'json' };
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const pjson = {
-    name: '@eightstate/escli',
-    version: '0.5.0',
-    type: 'module',
+    name: packageJson.name,
+    version: packageJson.version,
+    type: packageJson.type,
     oclif: {
         bin: 'escli',
         enableJsonFlag: true,
@@ -41,13 +42,19 @@ const rootManifestRequested = manifestRequested && argv.length === 0;
 const firstCommandToken = argv.shift() ?? (manifestRequested || versionRequested ? 'version' : undefined);
 let commandId = firstCommandToken;
 let registration = commandId ? commandsById.get(commandId) : undefined;
+// Multi-level command resolution: try longest match first (handles
+// `notion page read`, `notion db row update`, etc. where intermediate
+// prefixes like `notion page` aren't themselves registered).
 if (firstCommandToken && argv.length > 0) {
-    const nestedCommandId = `${firstCommandToken} ${argv[0]}`;
-    const nestedRegistration = commandsById.get(nestedCommandId);
-    if (nestedRegistration) {
-        commandId = nestedCommandId;
-        registration = nestedRegistration;
-        argv.shift();
+    for (let take = argv.length; take >= 1; take--) {
+        const candidateId = [firstCommandToken, ...argv.slice(0, take)].join(' ');
+        const candidateRegistration = commandsById.get(candidateId);
+        if (candidateRegistration) {
+            commandId = candidateId;
+            registration = candidateRegistration;
+            argv.splice(0, take);
+            break;
+        }
     }
 }
 if (argv.includes('--help') || argv.includes('-h'))