@forumulate/cli 0.3.6 → 0.4.0

package/dist/publish/docs-apply.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.payloadOf = payloadOf;
+exports.uploadAssetsFor = uploadAssetsFor;
+exports.applyDocs = applyDocs;
+exports.dryRunImports = dryRunImports;
+exports.applyPrune = applyPrune;
+exports.knownUrls = knownUrls;
+const frontmatter_1 = require("./frontmatter");
+const api_1 = require("./api");
+const context_1 = require("./context");
+const rewrite_1 = require("./rewrite");
+/**
+ * The writes a docs plan names, in the only order that works: collections
+ * before the pages filed in them, moves before the import that would otherwise
+ * refuse a page living in another collection, assets before the text that
+ * points at them.
+ *
+ * The bodies go through `POST …/docs/import` — the product's own converter,
+ * the door our own guides are published through — not page-by-page creates:
+ * it is the one place that understands every Markdown dialect we accept, and
+ * it publishes as it writes.
+ */
+/** Files per import call. Long calls are cut at the edge at 30 s while the work carries on. */
+const BATCH = 20;
+/** The text sent for one page: its address declared, links and assets pointed at the web. */
+function payloadOf(ctx, page, urls) {
+    if (page.stub)
+        return page.source;
+    const linked = (0, rewrite_1.rewriteLinks)(page.source, page.file, ctx.scan.slugByFile);
+    return (0, frontmatter_1.declareSlug)((0, rewrite_1.rewriteAssets)(linked, urls), page.slug);
+}
+/** Upload what the given files reference; the map is ref → URL, per file. */
+async function uploadAssetsFor(ctx, files, existing) {
+    const out = new Map();
+    const seen = new Map();
+    for (const file of files) {
+        const refs = ctx.scan.refs.get(file);
+        if (!refs)
+            continue;
+        const urls = new Map();
+        for (const [ref, abs] of refs) {
+            let url = seen.get(abs);
+            if (!url) {
+                const had = existing.size;
+                url = await ctx.api.upload(ctx.org, ctx.spaceId, abs, existing);
+                if (existing.size > had)
+                    ctx.line({ verb: 'upload', what: abs.slice(ctx.root.length + 1) || abs, detail: url });
+                seen.set(abs, url);
+            }
+            urls.set(ref, url);
+        }
+        out.set(file, urls);
+    }
+    return out;
+}
+/** Step 1-4: collections, moves, assets, bodies. Returns the asset URLs it used. */
+async function applyDocs(ctx, plan, existingAssets) {
+    const ids = new Map();
+    for (const [c, live] of plan.collectionOf)
+        if (live)
+            ids.set(c, live.id);
+    for (const c of plan.createCollections) {
+        const { collection } = await ctx.api.post((0, context_1.spacePath)(ctx, '/collections'), {
+            name: c.name,
+            slug: c.slug,
+            ...(c.nav ? { nav: c.nav } : {}),
+        });
+        ids.set(c, collection.id);
+        plan.collectionOf.set(c, collection);
+    }
+    for (const { live, body } of plan.patchCollections)
+        await ctx.api.patch((0, context_1.spacePath)(ctx, `/collections/${live.id}`), body);
+    for (const { page, to } of plan.moves) {
+        await ctx.api.post((0, context_1.spacePath)(ctx, `/pages/${page.id}/reorder`), { collectionId: ids.get(to) });
+    }
+    // Every file that is sent, and every page whose metadata names a local
+    // image, needs its assets before anything points at them.
+    const files = new Set();
+    for (const sends of plan.sends.values())
+        for (const s of sends)
+            files.add(s.page.file);
+    for (const c of ctx.scan.collections)
+        for (const p of c.pages)
+            if (Object.keys(p.meta).length && ctx.only.piece(ctx.spec, p.slug, p.file, c))
+                files.add(p.file);
+    const urls = await uploadAssetsFor(ctx, [...files], existingAssets);
+    for (const [c, sends] of plan.sends) {
+        const collectionId = ids.get(c);
+        for (let i = 0; i < sends.length; i += BATCH) {
+            const batch = sends.slice(i, i + BATCH);
+            const report = await ctx.api.post((0, context_1.spacePath)(ctx, '/docs/import'), {
+                files: batch.map((s) => ({
+                    name: s.page.importName,
+                    content: payloadOf(ctx, s.page, urls.get(s.page.file) ?? new Map()),
+                })),
+                collectionId,
+                onExisting: 'replace',
+            });
+            noteImport(ctx, c, report);
+        }
+    }
+    return urls;
+}
+/** A dry run with a token asks the importer itself, so the plan is the server's too. */
+async function dryRunImports(ctx, plan) {
+    for (const [c, sends] of plan.sends) {
+        const live = plan.collectionOf.get(c);
+        const urls = (file) => {
+            const refs = ctx.scan.refs.get(file);
+            const m = new Map();
+            // Not uploaded on a dry run: a placeholder keeps the reference a URL.
+            if (refs)
+                for (const ref of refs.keys())
+                    m.set(ref, `https://assets.invalid/${encodeURIComponent(ref)}`);
+            return m;
+        };
+        for (let i = 0; i < sends.length; i += BATCH) {
+            const batch = sends.slice(i, i + BATCH);
+            // `dryRun: true` is the importer's own promise to write nothing, so this
+            // one POST goes around the read-only guard on purpose.
+            const res = await ctx.api.opts.client
+                .request('POST', (0, context_1.spacePath)(ctx, '/docs/import'), {
+                body: {
+                    files: batch.map((s) => ({
+                        name: s.page.importName,
+                        content: payloadOf(ctx, s.page, urls(s.page.file)),
+                    })),
+                    ...(live ? { collectionId: live.id } : { collection: c.name }),
+                    onExisting: 'replace',
+                    dryRun: true,
+                },
+            })
+                .catch((e) => {
+                ctx.errors.push(`import dry run for ${c.slug}: ${e.status ?? ''} ${e.message}`);
+                return null;
+            });
+            if (res)
+                noteImport(ctx, c, res);
+        }
+    }
+}
+function noteImport(ctx, c, report) {
+    for (const f of report.failures ?? [])
+        ctx.errors.push(`${c.dir || '(root)'}/${f.file}: ${f.reason}`);
+    if ((report.failed ?? 0) > (report.failures?.length ?? 0))
+        ctx.errors.push(`${c.slug}: ${report.failed} file(s) failed to import`);
+    for (const s of report.refused ?? [])
+        ctx.errors.push(`${s}: refused by the importer`);
+    for (const b of report.brokenLinks ?? [])
+        ctx.line({ verb: 'warn', what: `page ${b.pageSlug}`, detail: `link to nothing: ${b.url}` });
+}
+/** `--prune`, last: pages to the trash, then the collections left empty. */
+async function applyPrune(ctx, plan) {
+    if (plan.prunePages.length)
+        await ctx.api.post((0, context_1.spacePath)(ctx, '/pages/bulk-delete'), {
+            ids: plan.prunePages.map((p) => p.id),
+        });
+    for (const c of plan.pruneCollections)
+        await ctx.api.del((0, context_1.spacePath)(ctx, `/collections/${c.id}`));
+}
+/**
+ * Per file: local reference → the URL it already has, for assets uploaded on
+ * an earlier run. A reference not uploaded yet keeps its local spelling, which
+ * is what makes a plan say "coverUrl would change" — because it would.
+ */
+function knownUrls(ctx, existing) {
+    return (file) => {
+        const out = new Map();
+        for (const [ref, abs] of ctx.scan.refs.get(file) ?? []) {
+            const url = existing.get((0, api_1.assetName)(abs));
+            if (url)
+                out.set(ref, url);
+        }
+        return out;
+    };
+}
+//# sourceMappingURL=docs-apply.js.map

package/dist/publish/docs-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-apply.js","sourceRoot":"","sources":["../../src/publish/docs-apply.ts"],"names":[],"mappings":"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"}

package/dist/publish/docs-plan.d.ts

@@ -0,0 +1,40 @@
+import type { SpaceCtx } from './context';
+import type { LiveCollection, LivePage, LocalCollection, LocalPage } from './types';
+/**
+ * What publishing a docs folder would WRITE: collections, page bodies, moves
+ * between collections and the prune. Metadata and order come after the write
+ * (`docs-reconcile.ts`), because they need the ids of pages this run creates.
+ */
+export interface DocsPlan {
+    /** Local collection → the live one it is, or undefined when it will be created. */
+    collectionOf: Map<LocalCollection, LiveCollection | undefined>;
+    createCollections: LocalCollection[];
+    patchCollections: {
+        live: LiveCollection;
+        body: Record<string, unknown>;
+    }[];
+    /** A page that exists in another collection than its folder says. */
+    moves: {
+        page: LivePage;
+        to: LocalCollection;
+    }[];
+    /** Per collection, the files to send to the importer. */
+    sends: Map<LocalCollection, {
+        page: LocalPage;
+        why: 'create' | 'update';
+    }[]>;
+    prunePages: LivePage[];
+    pruneCollections: LiveCollection[];
+    unchanged: number;
+}
+export interface DocsLive {
+    collections: LiveCollection[];
+    pages: LivePage[];
+    publicRows: Map<string, Record<string, unknown>>;
+}
+/** The live collection a folder is: by slug, then by name. */
+export declare function matchCollections(local: LocalCollection[], live: LiveCollection[], rootName?: string): Map<LocalCollection, LiveCollection | undefined>;
+/** How a live page's body is read for comparison: one walk authenticated, per page otherwise. */
+export type BodyOf = (page: LivePage) => Promise<string | null>;
+export declare function planDocs(ctx: SpaceCtx, live: DocsLive, bodyOf: BodyOf, openapiCollections: Set<string>): Promise<DocsPlan>;
+//# sourceMappingURL=docs-plan.d.ts.map

package/dist/publish/docs-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-plan.d.ts","sourceRoot":"","sources":["../../src/publish/docs-plan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,mFAAmF;IACnF,YAAY,EAAE,GAAG,CAAC,eAAe,EAAE,cAAc,GAAG,SAAS,CAAC,CAAC;IAC/D,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,gBAAgB,EAAE;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC5E,qEAAqE;IACrE,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,EAAE,EAAE,eAAe,CAAA;KAAE,EAAE,CAAC;IACjD,yDAAyD;IACzD,KAAK,EAAE,GAAG,CAAC,eAAe,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAA;KAAE,EAAE,CAAC,CAAC;IAC7E,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EAAE,EACxB,IAAI,EAAE,cAAc,EAAE,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,GAAG,CAAC,eAAe,EAAE,cAAc,GAAG,SAAS,CAAC,CAwBlD;AAED,iGAAiG;AACjG,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEhE,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC9B,OAAO,CAAC,QAAQ,CAAC,CA0GnB"}

package/dist/publish/docs-plan.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchCollections = matchCollections;
+exports.planDocs = planDocs;
+const compare_1 = require("./compare");
+/** The live collection a folder is: by slug, then by name. */
+function matchCollections(local, live, rootName) {
+    const out = new Map();
+    const taken = new Set();
+    for (const c of local) {
+        let hit;
+        if (c.dir === '' && !rootName) {
+            // Files at the root of the space go where the space files loose pages.
+            hit = live.find((l) => l.isDefault) ?? live.find((l) => l.slug === 'pages');
+            if (!hit) {
+                c.slug = 'pages';
+                c.name = 'Pages';
+            }
+            else {
+                c.slug = hit.slug;
+                c.name = hit.name;
+            }
+        }
+        else {
+            hit =
+                live.find((l) => !taken.has(l.id) && l.slug === c.slug) ??
+                    live.find((l) => !taken.has(l.id) && l.name.toLowerCase() === c.name.toLowerCase());
+        }
+        if (hit)
+            taken.add(hit.id);
+        out.set(c, hit);
+    }
+    return out;
+}
+async function planDocs(ctx, live, bodyOf, openapiCollections) {
+    const { scan, spec, only } = ctx;
+    const collectionOf = matchCollections(scan.collections, live.collections, spec.rootCollection);
+    const plan = {
+        collectionOf,
+        createCollections: [],
+        patchCollections: [],
+        moves: [],
+        sends: new Map(),
+        prunePages: [],
+        pruneCollections: [],
+        unchanged: 0,
+    };
+    const bySlug = new Map(live.pages.map((p) => [p.slug, p]));
+    // Every slug is one address in a space: two files claiming it is a conflict
+    // the author resolves, not one the publisher picks a winner in.
+    const owner = new Map();
+    for (const c of scan.collections)
+        for (const p of c.pages) {
+            const prev = owner.get(p.slug);
+            if (prev)
+                ctx.errors.push(`two files publish at "${p.slug}": ${prev} and ${p.file} — give one a \`slug:\``);
+            owner.set(p.slug, p.file);
+        }
+    for (const c of scan.collections) {
+        const inScope = (p) => only.piece(spec, p.slug, p.file, c);
+        const scoped = c.pages.filter(inScope);
+        const target = collectionOf.get(c);
+        if (!scoped.length && only.all === false)
+            continue;
+        if (!target) {
+            plan.createCollections.push(c);
+            ctx.line({
+                verb: 'create',
+                what: `collection ${c.slug}`,
+                detail: `"${c.name}" ← ${c.dir || '(space root)'}/`,
+            });
+        }
+        else {
+            const declared = spec.collections?.[c.dir];
+            const body = {};
+            // Only what the author SAID. A name derived from a folder must not
+            // overwrite one somebody chose in the studio on every run.
+            if (declared?.name && declared.name !== target.name)
+                body.name = declared.name;
+            if (c.nav && JSON.stringify({ ...target.nav, ...c.nav }) !== JSON.stringify(target.nav ?? {}))
+                body.nav = c.nav;
+            if (Object.keys(body).length) {
+                plan.patchCollections.push({ live: target, body });
+                ctx.line({
+                    verb: 'patch',
+                    what: `collection ${target.slug}`,
+                    detail: Object.keys(body).join(', '),
+                });
+            }
+        }
+        const sends = [];
+        for (const p of scoped) {
+            const existing = bySlug.get(p.slug);
+            if (!existing) {
+                sends.push({ page: p, why: 'create' });
+                ctx.line({ verb: 'create', what: `page ${p.slug}`, detail: `← ${p.file}` });
+                continue;
+            }
+            if (target && existing.collectionId !== target.id) {
+                plan.moves.push({ page: existing, to: c });
+                ctx.line({ verb: 'move', what: `page ${p.slug}`, detail: `into collection ${c.slug}` });
+            }
+            else if (!target) {
+                plan.moves.push({ page: existing, to: c });
+                ctx.line({ verb: 'move', what: `page ${p.slug}`, detail: `into new collection ${c.slug}` });
+            }
+            // A folder stub never overwrites a page that already stands for the folder.
+            if (p.stub) {
+                plan.unchanged++;
+                continue;
+            }
+            const reasons = [];
+            if (ctx.force)
+                reasons.push('--force');
+            if (!existing.published)
+                reasons.push('not published');
+            if (existing.title !== p.title)
+                reasons.push(`title "${existing.title}" → "${p.title}"`);
+            if (!reasons.length) {
+                const liveBody = await bodyOf(existing);
+                if (liveBody === null)
+                    reasons.push('content not readable');
+                else if (!(0, compare_1.sameText)(p.body, liveBody))
+                    reasons.push('content');
+            }
+            if (reasons.length) {
+                sends.push({ page: p, why: 'update' });
+                ctx.line({
+                    verb: 'update',
+                    what: `page ${p.slug}`,
+                    detail: `${reasons.join(', ')} ← ${p.file}`,
+                });
+            }
+            else
+                plan.unchanged++;
+        }
+        if (sends.length)
+            plan.sends.set(c, sends);
+        for (const p of scoped)
+            if (p.unknown.length)
+                ctx.line({
+                    verb: 'warn',
+                    what: `page ${p.slug}`,
+                    detail: `front matter not understood, not sent: ${p.unknown.join(', ')}`,
+                });
+    }
+    if (ctx.prune)
+        planPrune(ctx, live, plan, openapiCollections);
+    return plan;
+}
+/**
+ * `--prune`: what the folder no longer has.
+ *
+ * Never on a narrowed run, never a collection an OpenAPI import owns, never a
+ * slug or collection the manifest says to `keep`, and never a page with a kept
+ * page underneath it — deleting a parent takes its children to the trash with
+ * it, and "I removed one file" must not cost a subtree. Pages go to the trash,
+ * where they can be restored.
+ */
+function planPrune(ctx, live, plan, openapiCollections) {
+    if (!ctx.only.all) {
+        ctx.line({
+            verb: 'skip',
+            what: 'prune',
+            detail: 'not with --only — a narrowed run never deletes',
+        });
+        return;
+    }
+    const keep = new Set(ctx.spec.keep ?? []);
+    const wanted = new Set(ctx.scan.collections.flatMap((c) => c.pages.map((p) => p.slug)));
+    const managed = new Set([...plan.collectionOf.values()].filter(Boolean).map((c) => c.id));
+    const protectedCols = new Set(live.collections
+        .filter((c) => openapiCollections.has(c.name.toLowerCase()) ||
+        openapiCollections.has(c.slug) ||
+        keep.has(c.slug) ||
+        keep.has(c.name))
+        .map((c) => c.id));
+    const doomed = new Set(live.pages
+        .filter((p) => !wanted.has(p.slug) && !keep.has(p.slug) && !protectedCols.has(p.collectionId))
+        .map((p) => p.id));
+    const children = new Map();
+    for (const p of live.pages)
+        if (p.parentId)
+            children.set(p.parentId, [...(children.get(p.parentId) ?? []), p]);
+    const keepsSomething = (id) => (children.get(id) ?? []).some((c) => !doomed.has(c.id) || keepsSomething(c.id));
+    for (const p of live.pages) {
+        if (!doomed.has(p.id))
+            continue;
+        if (keepsSomething(p.id)) {
+            ctx.line({
+                verb: 'skip',
+                what: `prune ${p.slug}`,
+                detail: 'has pages under it that are kept',
+            });
+            continue;
+        }
+        plan.prunePages.push(p);
+        ctx.line({ verb: 'prune', what: `page ${p.slug}`, detail: 'no file — to the trash' });
+    }
+    const prunedIds = new Set(plan.prunePages.map((p) => p.id));
+    for (const c of live.collections) {
+        if (managed.has(c.id) || protectedCols.has(c.id) || c.isDefault)
+            continue;
+        const rest = live.pages.filter((p) => p.collectionId === c.id && !prunedIds.has(p.id));
+        if (rest.length)
+            continue;
+        plan.pruneCollections.push(c);
+        ctx.line({ verb: 'prune', what: `collection ${c.slug}`, detail: 'no folder' });
+    }
+}
+//# sourceMappingURL=docs-plan.js.map

package/dist/publish/docs-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-plan.js","sourceRoot":"","sources":["../../src/publish/docs-plan.ts"],"names":[],"mappings":"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"}

package/dist/publish/docs-reconcile.d.ts

@@ -0,0 +1,26 @@
+import { type SpaceCtx } from './context';
+import type { DocsLive } from './docs-plan';
+import type { LiveCollection, LocalCollection } from './types';
+/**
+ * After the bodies land: metadata, nesting and order.
+ *
+ * Run twice in a real publish — never, in fact, on a guess. On a dry run it
+ * reads the space as it is and says what would change; on a real run it reads
+ * the space AGAIN after the import, because the pages this run created only
+ * have ids now, and acts on that. One function, so the plan and the run cannot
+ * disagree about what "in order" means.
+ */
+export interface ReconcileInput {
+    live: DocsLive;
+    collectionOf: Map<LocalCollection, LiveCollection | undefined>;
+    /** Current metadata of a page, or null when it cannot be read (no token). */
+    metaOf: (pageId: string) => Promise<Record<string, unknown> | null>;
+    /** Per file: local reference → asset URL, for metadata that names a local image. */
+    urlsFor: (file: string) => Map<string, string>;
+    /** Shared across a run: whether `POST …/collections/{id}/order` exists. */
+    bulkOrder: {
+        available: boolean | undefined;
+    };
+}
+export declare function reconcileDocs(ctx: SpaceCtx, input: ReconcileInput, apply: boolean): Promise<void>;
+//# sourceMappingURL=docs-reconcile.d.ts.map

package/dist/publish/docs-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-reconcile.d.ts","sourceRoot":"","sources":["../../src/publish/docs-reconcile.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAa,MAAM,SAAS,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,EAAE,GAAG,CAAC,eAAe,EAAE,cAAc,GAAG,SAAS,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACpE,oFAAoF;IACpF,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,2EAA2E;IAC3E,SAAS,EAAE;QAAE,SAAS,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC;CAC/C;AAUD,wBAAsB,aAAa,CACjC,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC,CAgHf"}

package/dist/publish/docs-reconcile.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileDocs = reconcileDocs;
+const compare_1 = require("./compare");
+const context_1 = require("./context");
+const rewrite_1 = require("./rewrite");
+/** Keys a public page row carries, under the metadata name they compare with. */
+const PUBLIC_META = {
+    icon: 'icon',
+    tags: 'tags',
+    hideFromNav: 'hideFromNav',
+    seoDescription: 'description',
+};
+async function reconcileDocs(ctx, input, apply) {
+    const { live } = input;
+    const bySlug = new Map(live.pages.map((p) => [p.slug, p]));
+    const idOf = (slug) => bySlug.get(slug)?.id ?? `new:${slug}`;
+    const scoped = (c, p) => ctx.only.piece(ctx.spec, p.slug, p.file, c);
+    // ── Metadata ──────────────────────────────────────────────────────────────
+    for (const c of ctx.scan.collections) {
+        for (const p of c.pages) {
+            if (!scoped(c, p) || !Object.keys(p.meta).length)
+                continue;
+            const want = (0, rewrite_1.rewriteValue)(p.meta, input.urlsFor(p.file));
+            const page = bySlug.get(p.slug);
+            if (!page) {
+                if (apply)
+                    ctx.errors.push(`page ${p.slug} is missing after the import — metadata not set`);
+                else
+                    ctx.line({
+                        verb: 'meta',
+                        what: `page ${p.slug}`,
+                        detail: `set ${Object.keys(want).join(', ')} (new page)`,
+                    });
+                continue;
+            }
+            let current = await input.metaOf(page.id);
+            let unknown = [];
+            if (current === null) {
+                // Anonymous: the public row has a few of these; the rest cannot be compared.
+                const row = live.publicRows.get(page.id) ?? {};
+                current = {};
+                for (const k of Object.keys(want)) {
+                    if (PUBLIC_META[k])
+                        current[k] = row[PUBLIC_META[k]] ?? null;
+                    else
+                        unknown.push(k);
+                }
+            }
+            const keys = (0, compare_1.differingKeys)(current, want).filter((k) => !unknown.includes(k));
+            unknown = unknown.filter((k) => want[k] !== undefined);
+            if (unknown.length && !apply)
+                ctx.line({
+                    verb: 'meta',
+                    what: `page ${p.slug}`,
+                    detail: `cannot compare without a token: ${unknown.join(', ')}`,
+                });
+            if (!keys.length)
+                continue;
+            if (!apply) {
+                ctx.line({ verb: 'meta', what: `page ${p.slug}`, detail: keys.join(', ') });
+                continue;
+            }
+            await ctx.api.patch((0, context_1.spacePath)(ctx, `/pages/${page.id}/metadata`), Object.fromEntries(keys.map((k) => [k, want[k]])));
+            ctx.line({ verb: 'meta', what: `page ${p.slug}`, detail: keys.join(', ') });
+        }
+    }
+    // ── Nesting and order, one sibling group at a time ────────────────────────
+    for (const c of ctx.scan.collections) {
+        const col = input.collectionOf.get(c);
+        const cid = col?.id ?? `new:${c.slug}`;
+        const groups = new Map();
+        for (const p of c.pages)
+            groups.set(p.parentSlug, [...(groups.get(p.parentSlug) ?? []), p]);
+        for (const [parentSlug, pages] of groups) {
+            // A narrowed run orders a group only if it may touch every page in it.
+            if (!pages.every((p) => scoped(c, p)))
+                continue;
+            const pid = parentSlug === null ? null : idOf(parentSlug);
+            const desired = [...pages]
+                .sort((a, b) => a.order[0] - b.order[0] || a.order[1].localeCompare(b.order[1]))
+                .map((p) => idOf(p.slug));
+            // `GET …/pages` arrives in tree order; position in that list IS the order.
+            const current = live.pages
+                .filter((p) => p.collectionId === cid && p.parentId === pid)
+                .map((p) => p.id);
+            const placed = new Set(current);
+            const keep = (0, compare_1.stayPut)(desired.filter((id) => placed.has(id)), current);
+            const moving = desired.filter((id) => !keep.has(id));
+            if (!moving.length)
+                continue;
+            const where = `${c.slug}${parentSlug ? `/${parentSlug}` : ''}`;
+            const names = moving.map((id) => live.pages.find((p) => p.id === id)?.slug ?? id.replace(/^new:/, ''));
+            ctx.line({
+                verb: 'order',
+                what: where,
+                detail: `${moving.length} to place: ${names.slice(0, 8).join(', ')}${names.length > 8 ? ', …' : ''}`,
+            });
+            if (!apply)
+                continue;
+            if (pid?.startsWith('new:') || cid.startsWith('new:')) {
+                ctx.errors.push(`${where}: parent or collection missing after the import — order not set`);
+                continue;
+            }
+            await placeGroup(ctx, cid, pid, desired, moving, current, input.bulkOrder);
+        }
+    }
+    // ── Collection order ───────────────────────────────────────────────────────
+    if (!ctx.only.all)
+        return;
+    const desiredCols = ctx.scan.collections.map((c) => input.collectionOf.get(c)?.id ?? `new:${c.slug}`);
+    const currentCols = live.collections.map((c) => c.id).filter((id) => desiredCols.includes(id));
+    if (desiredCols.join() === currentCols.join())
+        return;
+    ctx.line({
+        verb: 'order',
+        what: 'collections',
+        detail: ctx.scan.collections.map((c) => c.slug).join(', '),
+    });
+    if (apply)
+        await ctx.api.post((0, context_1.spacePath)(ctx, '/collections/reorder'), {
+            ids: desiredCols.filter((id) => !id.startsWith('new:')),
+        });
+}
+/**
+ * Put one sibling group in order.
+ *
+ * `POST …/collections/{id}/order` does it in one call when the API
+ * has it; until then — and for any group it refuses — one paced
+ * `POST …/pages/{id}/reorder` per page that is out of place, each placed after
+ * its predecessor in the desired order. A page under the wrong parent is
+ * always moved one at a time, because that call is the one that re-parents.
+ */
+async function placeGroup(ctx, cid, pid, desired, moving, current, bulk) {
+    const reparent = moving.some((id) => !current.includes(id));
+    if (!reparent && bulk.available !== false) {
+        // Unmanaged siblings keep their relative order, after the managed ones.
+        const pageIds = [...desired, ...current.filter((id) => !desired.includes(id))];
+        try {
+            await ctx.api.post((0, context_1.spacePath)(ctx, `/collections/${cid}/order`), pid ? { pageIds, parentId: pid } : { pageIds });
+            bulk.available = true;
+            return;
+        }
+        catch (e) {
+            const status = e.status;
+            // 404/405: the route is not there (yet) — stop asking for the rest of the run.
+            if (status === 404 || status === 405)
+                bulk.available = false;
+            else if (status !== 400 && status !== 422)
+                throw e;
+        }
+    }
+    const keep = new Set(desired.filter((id) => !moving.includes(id)));
+    let prev = null;
+    for (const id of desired) {
+        if (!keep.has(id)) {
+            await ctx.api.post((0, context_1.spacePath)(ctx, `/pages/${id}/reorder`), { parentId: pid, afterId: prev });
+        }
+        prev = id;
+    }
+}
+//# sourceMappingURL=docs-reconcile.js.map