@mx-space/cli 0.15.0 → 0.15.1

package/dist/test/domain/envelope.test.js

@@ -0,0 +1,149 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { coerceMeta, flagToTag, listUnknownMetaKeys, parseEnvelope, tagToFlag, } from '../../src/domain/envelope';
+const fixture = (name) => readFileSync(path.resolve(__dirname, '../fixtures', name), 'utf8');
+describe('envelope parser (src)', () => {
+    it('parses mxpost envelope with meta and content', () => {
+        const xml = fixture('post.xml');
+        const parsed = parseEnvelope(xml, 'post');
+        expect(parsed.kind).toBe('post');
+        expect(parsed.meta.title).toBe('题名');
+        expect(parsed.meta.slug).toBe('my-post');
+        expect(parsed.meta.category).toBe('tech');
+        expect(parsed.meta.state).toBe('publish');
+        expect(parsed.meta.summary).toBe('摘要');
+        expect(parsed.meta.copyright).toBe('true');
+        expect(parsed.meta.pin).toBe('2026-05-14');
+        expect(parsed.meta.tags).toEqual(['foo', 'bar']);
+        expect(parsed.contentXml).toContain('<p>正文一</p>');
+        expect(parsed.contentXml).toContain('<h2>章节</h2>');
+    });
+    it('coerces meta types', () => {
+        const xml = fixture('post.xml');
+        const parsed = parseEnvelope(xml, 'post');
+        const coerced = coerceMeta(parsed.meta);
+        expect(coerced.title).toBe('题名');
+        expect(coerced.copyright).toBe(true);
+        expect(coerced.state).toBe('publish');
+        expect(coerced.tags).toEqual(['foo', 'bar']);
+    });
+    it('parses mxnote envelope', () => {
+        const xml = fixture('note.xml');
+        const parsed = parseEnvelope(xml, 'note');
+        expect(parsed.kind).toBe('note');
+        expect(parsed.meta.title).toBe('note title');
+        expect(parsed.meta.topic).toBe('life');
+        expect(parsed.meta.bookmark).toBe('false');
+        const coerced = coerceMeta(parsed.meta);
+        expect(coerced.bookmark).toBe(false);
+        expect(coerced.publicAt).toBe('2026-05-14T10:00:00Z');
+        expect(parsed.contentXml).toContain('<p>note body</p>');
+    });
+    it('preserves content tag attributes', () => {
+        const xml = `<mxpost>
+  <meta>
+    <title>t</title>
+  </meta>
+  <content>
+<p id="p1">See <a href="https://example.com?a=1&amp;b=2" target="_blank">example</a></p>
+<embed id="e1" url="https://x.com/innei/status/1" source="tweet" />
+  </content>
+</mxpost>`;
+        const parsed = parseEnvelope(xml, 'post');
+        expect(parsed.contentXml).toContain('<a href="https://example.com?a=1&amp;b=2" target="_blank">');
+        expect(parsed.contentXml).toContain('<embed id="e1" url="https://x.com/innei/status/1" source="tweet" />');
+    });
+    it('records line numbers for meta entries', () => {
+        const xml = fixture('post.xml');
+        const parsed = parseEnvelope(xml, 'post');
+        expect(parsed.sourceMap['meta.title']).toBe(3);
+        expect(parsed.sourceMap['meta.slug']).toBe(4);
+        expect(parsed.sourceMap.content).toBeGreaterThan(0);
+    });
+    it('throws ValidationXml on malformed XML', () => {
+        const xml = fixture('post-bad.xml');
+        expect(() => parseEnvelope(xml, 'post')).toThrowError(expect.objectContaining({ _tag: 'ValidationXml' }));
+    });
+    it('rejects wrong root tag', () => {
+        expect(() => parseEnvelope('<wrong></wrong>', 'post')).toThrowError(expect.objectContaining({ _tag: 'ValidationXml' }));
+    });
+    it('maps kebab-case flag to camelCase tag', () => {
+        expect(flagToTag('--pin-order')).toBe('pinOrder');
+        expect(flagToTag('--public-at')).toBe('publicAt');
+        expect(tagToFlag('pinOrder')).toBe('--pin-order');
+        expect(tagToFlag('publicAt')).toBe('--public-at');
+    });
+    it('reads pinOrder via meta and coerces to number', () => {
+        const xml = `<mxpost><meta><title>t</title><pinOrder>3</pinOrder></meta><content/></mxpost>`;
+        const parsed = parseEnvelope(xml, 'post');
+        expect(parsed.meta.pinOrder).toBe('3');
+        expect(coerceMeta(parsed.meta).pinOrder).toBe(3);
+    });
+    it('coerces all supported note/page/post meta fields', () => {
+        const coerced = coerceMeta({
+            category: 'tech',
+            topic: 'life',
+            summary: 's',
+            state: 'draft',
+            copyright: 'false',
+            pin: '2026-01-01',
+            pinOrder: 'not-a-number',
+            related: ['1', '2'],
+            tags: ['a'],
+            mood: 'calm',
+            weather: 'sunny',
+            publicAt: '2026-01-01T00:00:00Z',
+            password: 'secret',
+            bookmark: 'true',
+            location: 'Earth',
+            subtitle: 'Sub',
+            order: '4',
+            format: 'markdown',
+        });
+        expect(coerced).toMatchObject({
+            category: 'tech',
+            topic: 'life',
+            summary: 's',
+            state: 'draft',
+            copyright: false,
+            pin: '2026-01-01',
+            related: ['1', '2'],
+            tags: ['a'],
+            mood: 'calm',
+            weather: 'sunny',
+            publicAt: '2026-01-01T00:00:00Z',
+            password: 'secret',
+            bookmark: true,
+            location: 'Earth',
+            subtitle: 'Sub',
+            order: 4,
+            format: 'markdown',
+        });
+        expect(coerced.pinOrder).toBeUndefined();
+    });
+    it('reports unknown meta keys', () => {
+        expect(listUnknownMetaKeys({ title: 't', extra: 'x', another: 'y' }, ['title'])).toEqual(['extra', 'another']);
+    });
+    it('handles self-closing meta/content and CDATA content', () => {
+        const parsed = parseEnvelope(`<mxpost><meta><subtitle/><related><id>1</id><id>2</id></related></meta><content><![CDATA[<p>raw</p>]]></content></mxpost>`, 'post');
+        expect(parsed.meta.subtitle).toBe('');
+        expect(parsed.meta.related).toEqual(['1', '2']);
+        expect(parsed.contentXml).toBe('<![CDATA[<p>raw</p>]]>');
+        const empty = parseEnvelope('<mxpost><meta><title>t</title></meta><content/></mxpost>', 'post');
+        expect(empty.contentXml).toBe('');
+    });
+    it('throws ValidationXml for malformed comments, CDATA, tags, root content, and unterminated sections', () => {
+        const invalid = [
+            '<mxpost><!-- broken<meta></meta></mxpost>',
+            '<mxpost><![CDATA[ broken</mxpost>',
+            '<mxpost><meta></meta',
+            '<mxpost><meta></meta><extra/></mxpost>',
+            '<mxpost><meta><title>t</meta></mxpost>',
+            '<mxpost><meta></meta>',
+        ];
+        for (const xml of invalid) {
+            expect(() => parseEnvelope(xml, 'post')).toThrowError(expect.objectContaining({ _tag: 'ValidationXml' }));
+        }
+    });
+});

package/dist/test/domain/errors.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/domain/errors.test.js

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+import { AuthMissing, ConfigMissingApiUrl, ConfigMissingToken, exitCodeForError, exitCodeForTag, Generic, NetworkTimeout, ProfileInvalidName, ProfileNoneActive, ResourceNotFound, ServerError, toErrorEnvelope, UpdatePermissionDenied, UpdatePmUnknown, UpdateRegistryUnreachable, ValidationFailed, WriteRequiresExplicit, codeForTag, } from '../../src/domain/errors';
+describe('exitCodeForTag', () => {
+    it('returns 4 for WriteRequiresExplicit (profile.write_requires_explicit)', () => {
+        expect(exitCodeForTag('WriteRequiresExplicit')).toBe(4);
+    });
+    it('returns 4 for ProfileNoneActive', () => {
+        expect(exitCodeForTag('ProfileNoneActive')).toBe(4);
+    });
+    it('returns 5 for ProfileInvalidName', () => {
+        expect(exitCodeForTag('ProfileInvalidName')).toBe(5);
+    });
+    it('returns 5 for ValidationFailed', () => {
+        expect(exitCodeForTag('ValidationFailed')).toBe(5);
+    });
+    it('returns 5 for ConfigMissingApiUrl / ConfigMissingToken', () => {
+        expect(exitCodeForTag('ConfigMissingApiUrl')).toBe(5);
+        expect(exitCodeForTag('ConfigMissingToken')).toBe(5);
+    });
+    it('returns 3 for AuthMissing/Expired/Denied/Probe', () => {
+        expect(exitCodeForTag('AuthMissing')).toBe(3);
+        expect(exitCodeForTag('AuthExpired')).toBe(3);
+        expect(exitCodeForTag('AuthDenied')).toBe(3);
+        expect(exitCodeForTag('AuthProbe')).toBe(3);
+    });
+    it('returns 4 for network.* tags', () => {
+        expect(exitCodeForTag('NetworkTimeout')).toBe(4);
+        expect(exitCodeForTag('NetworkDns')).toBe(4);
+        expect(exitCodeForTag('NetworkRefused')).toBe(4);
+    });
+    it('returns 6 for ServerError, 7 for ResourceNotFound', () => {
+        expect(exitCodeForTag('ServerError')).toBe(6);
+        expect(exitCodeForTag('ResourceNotFound')).toBe(7);
+    });
+    it('returns sysexits codes for update sub-errors', () => {
+        expect(exitCodeForTag('UpdatePmUnknown')).toBe(70);
+        expect(exitCodeForTag('UpdatePermissionDenied')).toBe(73);
+        expect(exitCodeForTag('UpdateRegistryUnreachable')).toBe(75);
+    });
+    it('returns 2 for ArgvParse', () => {
+        expect(exitCodeForTag('ArgvParse')).toBe(2);
+    });
+    it('returns 1 for Generic and unknown', () => {
+        expect(exitCodeForTag('Generic')).toBe(1);
+    });
+});
+describe('exitCodeForError', () => {
+    it('reads the _tag from a CliError instance', () => {
+        const err = new WriteRequiresExplicit({ message: 'blocked' });
+        expect(exitCodeForError(err)).toBe(4);
+    });
+    it('returns 1 for a plain Error', () => {
+        expect(exitCodeForError(new Error('boom'))).toBe(1);
+    });
+    it('returns 1 for non-error values', () => {
+        expect(exitCodeForError('string error')).toBe(1);
+        expect(exitCodeForError(null)).toBe(1);
+        expect(exitCodeForError(undefined)).toBe(1);
+        expect(exitCodeForError(42)).toBe(1);
+    });
+    it('returns 1 for an object with an unknown _tag', () => {
+        expect(exitCodeForError({ _tag: 'NotAKnownTag' })).toBe(1);
+    });
+});
+describe('codeForTag — wire-format strings', () => {
+    it('preserves legacy MxsErrorCode string values', () => {
+        expect(codeForTag('AuthMissing')).toBe('auth.missing');
+        expect(codeForTag('WriteRequiresExplicit')).toBe('profile.write_requires_explicit');
+        expect(codeForTag('ProfileNoneActive')).toBe('profile.none_active');
+        expect(codeForTag('ProfileInvalidName')).toBe('profile.invalid_name');
+        expect(codeForTag('ValidationFailed')).toBe('validation.failed');
+        expect(codeForTag('ConfigMissingApiUrl')).toBe('config.missing.api_url');
+        expect(codeForTag('Generic')).toBe('generic');
+    });
+});
+describe('toErrorEnvelope', () => {
+    it('emits the spec §4 envelope shape for WriteRequiresExplicit', () => {
+        const err = new WriteRequiresExplicit({
+            message: 'writing to production requires explicit acknowledgement',
+            hint: 'pass --profile prod to confirm',
+            details: { profile: 'prod', api_url: 'https://blog.example.com' },
+        });
+        const env = toErrorEnvelope(err);
+        expect(env).toMatchObject({
+            ok: false,
+            code: 'profile.write_requires_explicit',
+            message: 'writing to production requires explicit acknowledgement',
+            hint: 'pass --profile prod to confirm',
+            details: { profile: 'prod', api_url: 'https://blog.example.com' },
+        });
+    });
+    it('falls back to the default message when none is provided', () => {
+        const env = toErrorEnvelope(new ConfigMissingApiUrl({}));
+        expect(env.message).toBe('API URL is not configured');
+        expect(env.code).toBe('config.missing.api_url');
+    });
+    it('omits details when undefined', () => {
+        const env = toErrorEnvelope(new Generic({ message: 'something broke' }));
+        expect(env).not.toHaveProperty('details');
+    });
+    it('omits hint when empty string', () => {
+        const env = toErrorEnvelope(new ValidationFailed({ message: 'bad input', hint: '' }));
+        expect(env).not.toHaveProperty('hint');
+    });
+    it('preserves AuthMissing wire code', () => {
+        const env = toErrorEnvelope(new AuthMissing({ message: 'not authed' }));
+        expect(env.code).toBe('auth.missing');
+    });
+    it('preserves NetworkTimeout wire code', () => {
+        const env = toErrorEnvelope(new NetworkTimeout({ message: 'slow' }));
+        expect(env.code).toBe('network.timeout');
+    });
+    it('preserves ServerError, ResourceNotFound, ConfigMissingToken codes', () => {
+        expect(toErrorEnvelope(new ServerError({})).code).toBe('server.error');
+        expect(toErrorEnvelope(new ResourceNotFound({})).code).toBe('resource.not_found');
+        expect(toErrorEnvelope(new ConfigMissingToken({})).code).toBe('config.missing.token');
+    });
+    it('preserves ProfileInvalidName / ProfileNoneActive codes', () => {
+        expect(toErrorEnvelope(new ProfileInvalidName({})).code).toBe('profile.invalid_name');
+        expect(toErrorEnvelope(new ProfileNoneActive({})).code).toBe('profile.none_active');
+    });
+    it('preserves update.* sub-codes', () => {
+        expect(toErrorEnvelope(new UpdatePmUnknown({})).code).toBe('update.pm_unknown');
+        expect(toErrorEnvelope(new UpdatePermissionDenied({})).code).toBe('update.permission_denied');
+        expect(toErrorEnvelope(new UpdateRegistryUnreachable({})).code).toBe('update.registry_unreachable');
+    });
+});

package/dist/test/domain/gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/domain/gate.test.js

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import { decideWriteGate, } from '../../src/domain/gate';
+function makeResolved(overrides = {}) {
+    return {
+        apiUrl: overrides.apiUrl ?? 'https://blog.example.com',
+        profileName: 'profileName' in overrides ? overrides.profileName : 'prod',
+        isProduction: overrides.isProduction ?? false,
+        profileExplicit: overrides.profileExplicit ?? false,
+        urlOverridden: overrides.urlOverridden ?? false,
+    };
+}
+describe('decideWriteGate — safe methods always allow', () => {
+    it.each(['GET', 'HEAD', 'OPTIONS'])('allows %s even on production without explicit profile', (method) => {
+        const resolved = makeResolved({ isProduction: true });
+        expect(decideWriteGate(resolved, method).allow).toBe(true);
+    });
+});
+describe('decideWriteGate — non-production always allow', () => {
+    it.each(['POST', 'PUT', 'PATCH', 'DELETE'])('allows %s when isProduction is false', (method) => {
+        const resolved = makeResolved({ isProduction: false });
+        expect(decideWriteGate(resolved, method).allow).toBe(true);
+    });
+});
+describe('decideWriteGate — explicit profile bypasses gate', () => {
+    it.each(['POST', 'PUT', 'PATCH', 'DELETE'])('allows %s when profileExplicit is true', (method) => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: true,
+        });
+        expect(decideWriteGate(resolved, method).allow).toBe(true);
+    });
+});
+describe('decideWriteGate — URL override bypasses gate', () => {
+    it.each(['POST', 'PUT', 'PATCH', 'DELETE'])('allows %s when urlOverridden is true', (method) => {
+        const resolved = makeResolved({
+            isProduction: true,
+            urlOverridden: true,
+        });
+        expect(decideWriteGate(resolved, method).allow).toBe(true);
+    });
+});
+describe('decideWriteGate — production + implicit selection → refuse', () => {
+    it.each(['POST', 'PUT', 'PATCH', 'DELETE'])('refuses %s on production profile selected implicitly', (method) => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: false,
+            urlOverridden: false,
+            profileName: 'prod',
+            apiUrl: 'https://blog.example.com',
+        });
+        const decision = decideWriteGate(resolved, method);
+        expect(decision.allow).toBe(false);
+        expect(decision.message).toContain('prod');
+        expect(decision.message).toContain('https://blog.example.com');
+    });
+});
+describe('decideWriteGate — refusal message format', () => {
+    it('includes profile name and api url in message', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: false,
+            urlOverridden: false,
+            profileName: 'prod',
+            apiUrl: 'https://blog.example.com',
+        });
+        const decision = decideWriteGate(resolved, 'POST');
+        expect(decision.message).toContain('prod');
+        expect(decision.message).toContain('https://blog.example.com');
+    });
+    it('hint instructs to use --profile or MXS_PROFILE', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: false,
+            urlOverridden: false,
+            profileName: 'myprod',
+            apiUrl: 'https://blog.example.com',
+        });
+        const decision = decideWriteGate(resolved, 'DELETE');
+        expect(decision.hint).toMatch(/--profile myprod/);
+        expect(decision.hint).toMatch(/MXS_PROFILE=myprod/);
+    });
+    it('matches spec hint format exactly', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: false,
+            urlOverridden: false,
+            profileName: 'prod',
+        });
+        const decision = decideWriteGate(resolved, 'PATCH');
+        expect(decision.hint).toBe("active profile 'prod' is production; retry with --profile prod or MXS_PROFILE=prod");
+    });
+    it('uses "unknown" when profileName is null', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: false,
+            urlOverridden: false,
+            profileName: null,
+        });
+        const decision = decideWriteGate(resolved, 'POST');
+        expect(decision.message).toContain('unknown');
+    });
+});
+describe('decideWriteGate — all four conditions must hold to refuse', () => {
+    it('allows when only isProduction=true but urlOverridden=true', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            urlOverridden: true,
+            profileExplicit: false,
+        });
+        expect(decideWriteGate(resolved, 'POST').allow).toBe(true);
+    });
+    it('allows when isProduction=true and profileExplicit=true', () => {
+        const resolved = makeResolved({
+            isProduction: true,
+            profileExplicit: true,
+            urlOverridden: false,
+        });
+        expect(decideWriteGate(resolved, 'DELETE').allow).toBe(true);
+    });
+    it('allows when isProduction=false regardless of explicitness', () => {
+        const resolved = makeResolved({
+            isProduction: false,
+            profileExplicit: false,
+            urlOverridden: false,
+        });
+        expect(decideWriteGate(resolved, 'PUT').allow).toBe(true);
+    });
+});

package/dist/test/domain/payload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/domain/payload.test.js

@@ -0,0 +1,259 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { NodeContext } from '@effect/platform-node';
+import { Effect, Layer } from 'effect';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { buildNotePayload, buildPagePayload, buildPostPayload, emptyPayload, loadEnvelopeIfAny, } from '../../src/domain/payload';
+import { Lexical } from '../../src/services/Lexical';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mxs-next-create-'));
+});
+const TestLayer = Layer.mergeAll(Lexical.Default, NodeContext.layer);
+const run = (eff) => Effect.runPromise(Effect.provide(eff, TestLayer));
+describe('buildPostPayload (src)', () => {
+    it('builds payload from inline lexical content via flags', async () => {
+        const built = await run(buildPostPayload({
+            title: 't',
+            slug: 's',
+            category: 'tech',
+            content: '<p>hello</p>',
+            format: 'lexical',
+        }));
+        expect(built.payload.title).toBe('t');
+        expect(built.payload.slug).toBe('s');
+        expect(built.payload.__categoryName).toBe('tech');
+        expect(built.payload.contentFormat).toBe('lexical');
+        expect(typeof built.payload.content).toBe('string');
+        const parsed = JSON.parse(built.payload.content);
+        expect(parsed.root.type).toBe('root');
+        expect(typeof built.payload.text).toBe('string');
+    });
+    it('reads --content=file=<path>', async () => {
+        const filePath = path.join(tmpDir, 'body.xml');
+        await fs.writeFile(filePath, '<p>file body</p>', 'utf8');
+        const built = await run(buildPostPayload({
+            title: 't',
+            slug: 's',
+            category: 'tech',
+            content: `file=${filePath}`,
+            format: 'lexical',
+        }));
+        expect(built.contentSource).toBe('flag');
+        expect(built.payload.content.length).toBeGreaterThan(0);
+    });
+    it('falls back to envelope content when no --content', async () => {
+        const filePath = path.join(tmpDir, 'post.xml');
+        await fs.writeFile(filePath, `<mxpost>
+  <meta>
+    <title>envtitle</title>
+    <slug>envslug</slug>
+    <category>tech</category>
+  </meta>
+  <content>
+<p>env body</p>
+  </content>
+</mxpost>`, 'utf8');
+        const built = await run(buildPostPayload({ file: filePath }));
+        expect(built.payload.title).toBe('envtitle');
+        expect(built.payload.slug).toBe('envslug');
+        expect(built.payload.__categoryName).toBe('tech');
+        expect(built.contentSource).toBe('envelope');
+    });
+    it('flag overrides envelope meta', async () => {
+        const filePath = path.join(tmpDir, 'post.xml');
+        await fs.writeFile(filePath, `<mxpost>
+  <meta>
+    <title>envtitle</title>
+    <state>publish</state>
+  </meta>
+  <content>
+<p>env body</p>
+  </content>
+</mxpost>`, 'utf8');
+        const built = await run(buildPostPayload({
+            file: filePath,
+            title: 'flagtitle',
+            state: 'draft',
+        }));
+        expect(built.payload.title).toBe('flagtitle');
+        expect(built.payload.isPublished).toBe(false);
+    });
+    it('refuses lexical content when empty', async () => {
+        await expect(run(buildPostPayload({
+            title: 't',
+            slug: 's',
+            category: 'tech',
+            content: '',
+            format: 'lexical',
+        }))).rejects.toThrowError(/content is required/);
+    });
+    it('keeps markdown content identity', async () => {
+        const built = await run(buildPostPayload({
+            title: 't',
+            slug: 's',
+            category: 'tech',
+            content: '# hello',
+            format: 'markdown',
+        }));
+        expect(built.payload.contentFormat).toBe('markdown');
+        expect(built.payload.content).toBe('# hello');
+        expect(built.payload.text).toBe('# hello');
+    });
+    it('accepts metadata JSON, arrays, pinning, and related ids', async () => {
+        const metaPath = path.join(tmpDir, 'meta.json');
+        await fs.writeFile(metaPath, '{"canonical":"x"}', 'utf8');
+        const built = await run(buildPostPayload({
+            title: 't',
+            slug: 's',
+            content: '# hello',
+            format: 'markdown',
+            summary: 'summary',
+            state: 'publish',
+            tags: ['a', 'b'],
+            copyright: true,
+            pin: '2026-01-01',
+            pinOrder: 2,
+            related: ['p1', 'p2'],
+            meta: `file=${metaPath}`,
+        }));
+        expect(built.payload).toMatchObject({
+            summary: 'summary',
+            isPublished: true,
+            tags: ['a', 'b'],
+            copyright: true,
+            pin: '2026-01-01',
+            pinOrder: 2,
+            relatedId: ['p1', 'p2'],
+            meta: { canonical: 'x' },
+        });
+    });
+});
+describe('buildNotePayload', () => {
+    it('builds a default-titled note with coordinates, images, metadata, and markdown content', async () => {
+        const built = await run(buildNotePayload({
+            topic: 'life',
+            content: 'note body',
+            format: 'markdown',
+            state: 'draft',
+            mood: 'calm',
+            weather: 'sunny',
+            publicAt: '2026-01-01T00:00:00Z',
+            password: 'secret',
+            bookmark: true,
+            coords: '1.5,2.5',
+            location: 'Earth',
+            images: '["a.png"]',
+            meta: '{"source":"test"}',
+        }));
+        expect(built.payload).toMatchObject({
+            title: '无题',
+            __topicName: 'life',
+            isPublished: false,
+            mood: 'calm',
+            weather: 'sunny',
+            publicAt: '2026-01-01T00:00:00Z',
+            password: 'secret',
+            bookmark: true,
+            coordinates: { latitude: 1.5, longitude: 2.5 },
+            location: 'Earth',
+            images: ['a.png'],
+            meta: { source: 'test' },
+            contentFormat: 'markdown',
+            content: 'note body',
+        });
+    });
+    it('rejects invalid note coordinates', async () => {
+        const err = await run(Effect.flip(buildNotePayload({ coords: 'north,east' })));
+        expect(err._tag).toBe('ValidationFailed');
+        expect(err.message).toContain('invalid --coords');
+    });
+    it('loads note fields from an envelope and lets flags override them', async () => {
+        const filePath = path.join(tmpDir, 'note.xml');
+        await fs.writeFile(filePath, `<mxnote>
+  <meta>
+    <title>env note</title>
+    <slug>env-note</slug>
+    <topic>life</topic>
+    <state>publish</state>
+    <bookmark>false</bookmark>
+    <format>markdown</format>
+  </meta>
+  <content>env body</content>
+</mxnote>`, 'utf8');
+        const built = await run(buildNotePayload({ file: filePath, title: 'flag note' }));
+        expect(built.payload).toMatchObject({
+            title: 'flag note',
+            slug: 'env-note',
+            __topicName: 'life',
+            isPublished: true,
+            bookmark: false,
+            content: 'env body',
+        });
+        expect(built.contentSource).toBe('envelope');
+    });
+});
+describe('buildPagePayload', () => {
+    it('builds page payload from flags and markdown content', async () => {
+        const built = await run(buildPagePayload({
+            title: 'Page',
+            slug: 'page',
+            subtitle: 'Sub',
+            order: 3,
+            content: 'page body',
+            format: 'markdown',
+            meta: '{"layout":"plain"}',
+        }));
+        expect(built.payload).toMatchObject({
+            title: 'Page',
+            slug: 'page',
+            subtitle: 'Sub',
+            order: 3,
+            contentFormat: 'markdown',
+            content: 'page body',
+            meta: { layout: 'plain' },
+        });
+    });
+    it('loads page payload from mxpost envelope shape', async () => {
+        const filePath = path.join(tmpDir, 'page.xml');
+        await fs.writeFile(filePath, `<mxpost>
+  <meta>
+    <title>Env Page</title>
+    <slug>env-page</slug>
+    <subtitle>Env Sub</subtitle>
+    <order>7</order>
+    <format>markdown</format>
+  </meta>
+  <content>env page body</content>
+</mxpost>`, 'utf8');
+        const built = await run(buildPagePayload({ file: filePath }));
+        expect(built.payload).toMatchObject({
+            title: 'Env Page',
+            slug: 'env-page',
+            subtitle: 'Env Sub',
+            order: 7,
+            content: 'env page body',
+        });
+    });
+});
+describe('payload helpers', () => {
+    it('returns null when no envelope file is provided', async () => {
+        await expect(run(loadEnvelopeIfAny(undefined, 'post'))).resolves.toBeNull();
+    });
+    it('loads envelope through file= content specs', async () => {
+        const filePath = path.join(tmpDir, 'post.xml');
+        await fs.writeFile(filePath, '<mxpost><meta><title>t</title></meta><content>body</content></mxpost>', 'utf8');
+        const envelope = await run(loadEnvelopeIfAny(`file=${filePath}`, 'post'));
+        expect(envelope?.meta.title).toBe('t');
+    });
+    it('creates empty markdown and lexical payloads', async () => {
+        await expect(run(emptyPayload('markdown'))).resolves.toEqual({
+            content: '',
+            text: '',
+        });
+        const lexical = await run(emptyPayload('lexical'));
+        expect(JSON.parse(lexical.content).root.children).toEqual([]);
+        expect(lexical.text).toBe('');
+    });
+});