@mulmoclaude/core 3.15.0 → 4.0.0

package/dist/collection/server/publishProject.d.ts

@@ -1,332 +0,0 @@
-import { CollectionSchema } from '../core/schema';
-import { AppViewConfigDoc, NormalizedView, ProjectedViewCollection, ProjectedViewWrite, ViewAudience } from './appViews';
-import { AuthoredApp, AuthoredCollectionConfig } from './publishManifest';
-/** Who and when. Threaded in rather than read from a clock inside the
- *  projection so the projection stays pure and the tests can assert on an
- *  exact document. */
-export interface PublishStamp {
-    /** The publisher's Firebase uid. The rules require `owner ==
-     *  request.auth.uid` on CREATE and `owner` unchanged on UPDATE, so this is
-     *  used only when the app document does not exist yet. */
-    uid: string;
-    /** The publisher's verified email — the principal the roster is keyed by. */
-    email: string;
-    /** Wall-clock millis of this publish. */
-    publishedAt: number;
-    /** The git commit the declaration was read from, when the host could
-     *  resolve one. Absent is a normal state (a dirty tree, a repository
-     *  without git), and absent is more honest than a fabricated value. */
-    commit?: string | undefined;
-    /** Was the working tree modified when the commit was read?
-     *
-     *  Recorded as `publishedDirty` on the app document, because a commit that
-     *  does not describe what was published is worse than no commit: it looks
-     *  auditable. Publish-owned like the rest of the `published*` family — a
-     *  deploy must not drop the marker, and a later CLEAN publish must clear it
-     *  rather than inherit it forever. */
-    dirty?: boolean | undefined;
-}
-/** One collection's published schema document (`apps/{aid}/collections/{cid}`).
- *
- *  The rules never read `publishedSchema` — `schemaRead` gates the whole
- *  document and stops there. It is here for the CLIENTS: a member's host
- *  renders from it, and a public webview has no other way to know the fields.
- *  The whole schema is published rather than a projection of it, because
- *  every attempt to guess "the part a view needs" is a guess about a view
- *  that has not been written yet. */
-export interface PublishedSchemaDoc extends Record<string, unknown> {
-    publishedSchema: CollectionSchema;
-    publishedAt: number;
-    publishedBy: string;
-    publishedCommit?: string;
-}
-/** A STAGED schema document (`apps/{aid}/staging/{cid}`) — what deploy writes
- *  and what `/staging/{aid}` renders from.
- *
- *  Its provenance keys are `deployed*`, not `published*`. The two are different
- *  questions with different answers at almost every moment: `published*` says
- *  which revision the PUBLIC is looking at, and a deploy must not move it —
- *  otherwise staging a draft rewrites the recorded public revision (and, with
- *  `previousPublished`, the thing a rollback would restore) before anyone has
- *  published anything. */
-export interface StagedSchemaDoc extends Record<string, unknown> {
-    publishedSchema: CollectionSchema;
-    /** This collection's RULE-FACING configuration (`transitions`, `immutable`,
-     *  `submitOnly`, `peerVisibility`, …) — staged with the schema, not written
-     *  straight onto the app document.
-     *
-     *  It has to be staged for the same reason the `public` block is: the rules
-     *  read `apps/{aid}.collections[cid]` when they authorize a PUBLIC write, so
-     *  a deploy that landed it would change what anonymous visitors may do
-     *  before anyone published. The cost is that `/staging/{aid}` exercises the
-     *  new schema against the CURRENTLY PUBLISHED rule configuration; that is
-     *  the safe direction to be wrong in. */
-    config?: AuthoredCollectionConfig;
-    /** Whether this cid is in `participantRead` — same reason, same treatment. */
-    participantRead?: boolean;
-    deployedAt: number;
-    deployedBy: string;
-    deployedCommit?: string;
-}
-/** The public settings document (`apps/{aid}/config/public`).
- *
- *  `allow read: if true` — this is the one document an anonymous visitor can
- *  read, and it is the reason `apps/{aid}` itself is reader-only: a
- *  participant reading the app document would see their classmates'
- *  addresses. So the roster is NOT here, and neither is `owner`. What is here
- *  is what a public form needs in order to render itself and to tell a visitor
- *  "this closed yesterday" instead of failing a write with no explanation. */
-export interface PublishedConfigDoc extends Record<string, unknown> {
-    name?: string;
-    enabled: boolean;
-    read: string[];
-    submit: Record<string, Record<string, unknown>>;
-    /** That the app HAS a published view, and which datasets it asked for.
-     *
-     *  This is the only place the public page can learn it: the rules' app
-     *  document is reader-only and deliberately carries no view, and the HTML
-     *  itself lands in a SEPARATE document (`config/view`) because a 1 MiB limit
-     *  applies per document. Omitted here, the page has the HTML and no idea
-     *  what to send it — the feature does not work at all.
-     *
-     *  The authored PATH is deliberately not published. It names a file in the
-     *  author's repository, which the browser cannot use and which nobody should
-     *  be handed on a world-readable document; what the page needs is the
-     *  dataset list, and `publishedAt` beside it is what pins this declaration
-     *  to the HTML published in the same run. */
-    view?: {
-        collections: string[];
-    };
-    publishedAt: number;
-}
-/** Everything one publish writes. Separate documents because they live at
- *  separate paths with separate rules — and in the order given: the app
- *  document authorizes the other two, so it goes first. */
-export interface PublishedApp {
-    app: Record<string, unknown>;
-    schemas: {
-        cid: string;
-        doc: PublishedSchemaDoc;
-    }[];
-    config: PublishedConfigDoc;
-}
-/** The document id under `apps/{aid}/config`. One document, named, rather than
- *  a spread of them: a second public document is a second thing to keep in
- *  step, and nothing yet needs one. */
-export declare const PUBLIC_CONFIG_DOC = "public";
-/** Project the authored declaration into the documents publish writes.
- *
- *  `existing` is the app document as it is in Firestore right now, or null on
- *  a first publish. Two things need it, both required by the rules:
- *    - `owner` must be UNCHANGED on update. Re-stamping the publisher's uid
- *      would be refused for any app whose owner ever signed in as a different
- *      account, and would silently transfer ownership if it were not.
- *    - `previousPublished` is that document, so a rollback has something to
- *      put back.
- *
- *  Pure: no clock, no filesystem, no Firestore. Everything variable arrives as
- *  a parameter, which is what makes the conversion table testable as a table. */
-export declare function projectApp(authored: AuthoredApp, schemas: {
-    cid: string;
-    schema: CollectionSchema;
-}[], stamp: PublishStamp, existing: Record<string, unknown> | null): PublishedApp;
-/** Everything `deploy` writes — the host's staging half of the split (the
- *  design's D10).
- *
- *  Two things are deliberately ABSENT from the app document here:
- *
- *  - **`public`**. That block is what the rules read to authorize anonymous
- *    access (`publicOn` / `subOpen` read `apps/{aid}.public`, never the
- *    world-readable `config/public`), so writing it on deploy would open the
- *    app the moment someone deployed to test. It belongs to `publish`.
- *  - **the published schemas**. They go to `staging/{cid}`, which only the
- *    roster can read, so a deploy against a LIVE app does not swap the view
- *    its visitors are looking at.
- *
- *  A host writing this must MERGE the app document rather than replace it:
- *  a replace would drop a `public` block a previous publish put there and
- *  silently unpublish the app. */
-export interface DeployedApp {
-    /** The COMPLETE app document. **Write it with `set`, replacing — never with
-     *  `{ merge: true }`.**
-     *
-     *  A merge cannot DELETE, and every deletion here is a permission change:
-     *  removing `members.<email>` revokes access, and a merge would leave the
-     *  entry live. Worse, the rules require `memberEmails` to equal the keys of
-     *  `members` (`membersConsistent()`), so a merged member-removal is rejected
-     *  outright — a deploy that silently does nothing would be the good case.
-     *
-     *  Everything publish owns is carried through from `existing` verbatim, so
-     *  replacing does not unpublish a live app. */
-    app: Record<string, unknown>;
-    /** The staged schema documents, for `apps/{aid}/staging/{cid}`. */
-    staging: {
-        cid: string;
-        doc: StagedSchemaDoc;
-    }[];
-}
-export declare function projectDeploy(authored: AuthoredApp, schemas: {
-    cid: string;
-    schema: CollectionSchema;
-}[], stamp: PublishStamp, existing: Record<string, unknown> | null): DeployedApp;
-/** Everything `publish` writes that is NOT a promotion — the public face.
- *
- *  The schemas are absent on purpose: publish PROMOTES the documents deploy
- *  staged (copy `staging/{cid}` → `collections/{cid}`, re-stamped with
- *  {@link promoteSchema}) rather than re-projecting them from git. What the
- *  roster tested is then exactly what ships; re-projecting would publish
- *  whatever the working tree says at publish time, which nobody has looked at
- *  through `/staging/{aid}`.
- *
- *  WRITE `public` LAST. It is the only one of the three that grants anything,
- *  so a partial failure with it last leaves the app private (fail closed).
- *  See the design note's publish ordering. */
-export interface PublishedFace {
-    /** The COMPLETE app document **without `public`** — write it with `set`,
-     *  replacing.
-     *
-     *  Replacing (not merging) is what lets a key DISAPPEAR: withdrawing a
-     *  collection's rule configuration, or taking `public` out of `app.json`,
-     *  has to actually remove the field. Everything deploy owns is carried
-     *  through from `existing`, so publishing does not revert an invitation.
-     *
-     *  `public` is absent HERE on purpose — see {@link PublishedFace.public}. */
-    app: Record<string, unknown>;
-    /** `apps/{aid}/config/public` — the world-readable projection. */
-    config: PublishedConfigDoc;
-    /** The `public` block, to be written **LAST, as its own update** — or, when
-     *  `undefined`, DELETED from the app document (that is how an app becomes
-     *  private again).
-     *
-     *  Separate from {@link PublishedFace.app} because it is the only one of
-     *  publish's writes that GRANTS anything: the rules authorize anonymous
-     *  reads and submissions from `apps/{aid}.public`. Writing it inside the
-     *  replacement document would open the app before the promoted schemas and
-     *  the world-readable config exist, so a failure part-way would leave
-     *  anonymous access live against a half-published surface. Written last, the
-     *  same failure leaves the app private — which is the direction to fail in.
-     *
-     *  A re-publish therefore passes through a moment with no `public` block.
-     *  That is a brief denial for visitors, not a brief exposure. */
-    public: Record<string, unknown> | undefined;
-}
-/** The rule-facing configuration to promote, read from the STAGED documents
- *  rather than from the manifest as it reads right now.
- *
- *  Otherwise: deploy revision A, edit `app.json` to revision B, publish — and
- *  the promoted schema is A's while the authorization behaviour is B's, a
- *  combination nobody exercised through `/staging/{aid}`.
- *
- *  (`public` is deliberately NOT part of this: it is not staged, because it is
- *  the decision being made AT publish rather than something under test.) */
-export declare function stagedRuleConfig(staged: {
-    cid: string;
-    doc: StagedSchemaDoc;
-}[]): {
-    collections: Record<string, AuthoredCollectionConfig> | undefined;
-    participantRead: string[] | undefined;
-};
-export declare function projectPublish(authored: AuthoredApp, staged: {
-    cid: string;
-    doc: StagedSchemaDoc;
-}[], stamp: PublishStamp, existing: Record<string, unknown> | null): PublishedFace;
-/** Re-stamp a staged schema document as it is promoted to `collections/{cid}`.
- *
- *  The stamp answers "which version is PUBLIC right now, and who made it so",
- *  so it is written by the operation that changes the answer — publish — not
- *  carried over from the deploy that staged it. */
-export declare function promoteSchema(staged: StagedSchemaDoc, stamp: PublishStamp): PublishedSchemaDoc;
-/** The app documents' parent path — the `FirestoreDocs` seam takes a
- *  collection path plus a document id, and the app document's id is the aid. */
-export declare const APPS_COLLECTION = "apps";
-/** The collection (schema) documents' parent path — what the PUBLIC page
- *  reads, written only by publish (promotion). */
-export declare const appSchemasPath: (aid: string) => string;
-/** The URL-slug reservations — `appSlugs/{slug}` → `{ aid, published }`.
- *
- *  A TOP-LEVEL collection, not a field on the app: the public page resolves a
- *  slug to an aid BEFORE it can read anything under `apps/{aid}`, and a slug
- *  has to be claimable atomically (create-if-absent) so two apps cannot hold
- *  the same URL.
- *
- *  `published` is what makes the reservation invisible until publish. The slug
- *  is human-readable, so a readable reservation would let anyone guess the URL
- *  and get the aid — and the aid is the `/staging/{aid}` entrance. The rule is
- *  `allow read: if resource.data.published == true`, which needs no `get()` and
- *  so costs nothing against the rules' expression budget. */
-export declare const APP_SLUGS_COLLECTION = "appSlugs";
-/** The reservation document. Written by deploy as `{ aid, published: false }`
- *  and flipped by publish — never re-pointed at another aid, which the rules
- *  enforce on update. */
-export interface AppSlugDoc extends Record<string, unknown> {
-    aid: string;
-    published: boolean;
-}
-export declare const appSlugDoc: (aid: string, published: boolean) => AppSlugDoc;
-/** The staged schema documents' parent path — what `/staging/{aid}` reads,
- *  written by deploy. A separate DOCUMENT rather than a field beside
- *  `publishedSchema`, because the rules cannot hide a field: anything inside a
- *  document the public page may read is public. */
-export declare const appStagingPath: (aid: string) => string;
-/** The public-config documents' parent path. */
-export declare const appConfigPath: (aid: string) => string;
-/** Where one audience's pages live. `member` is read by anyone holding a role;
- *  `roster` by anyone on the roster, participants included. */
-export declare const appViewTierPath: (aid: string, tier: "member" | "roster") => string;
-/** One audience's tier, as publish (or deploy) must write it.
- *
- *  Both tiers are returned even when empty, deliberately. An app that WITHDREW
- *  its member pages produces an empty tier, and a host that only ever saw the
- *  tiers with something in them would leave the previous pages live — the
- *  failure `config/view` already had, where a declaration was withdrawn and
- *  the world went on reading the page. */
-export interface AppViewTier {
-    tier: "member" | "roster";
-    audience: Exclude<ViewAudience, "public">;
-    /** The projection document, for `{tier}/live:config` or `{tier}/staged:config`.
-     *  Meaningless when `views` is empty — the host deletes the tier instead. */
-    config: AppViewConfigDoc;
-    /** The views to publish, in declaration order. The host reads each `path`
-     *  and writes it to `{tier}/live:{id}`. */
-    views: NormalizedView[];
-}
-/** Project the declaration into the per-audience documents.
- *
- *  Pure, like `projectApp`: the HTML is not here (the host reads the files),
- *  and neither is the clock. What is here is the answer to "what may this
- *  audience read, and how" — computed once, so the page never has to guess and
- *  never has to discover it from a denial. */
-/** What the RULES will be in force with, as against what the manifest says.
- *
- *  `projectPublish` replaces BOTH `participantRead` and `collections` with what
- *  the staged schemas carry, so at publish the promoted pair is what decides
- *  whether a read is allowed and which transitions exist. They travel together
- *  deliberately: passing one and not the other publishes a page whose datasets
- *  follow revision A and whose buttons follow revision B.
- *
- *  At DEPLOY the manifest is exactly what is being staged, so the default is
- *  right — and today deploy is the only caller, because publish PROMOTES the
- *  staged documents rather than re-projecting them. */
-export interface PromotedRuleConfig {
-    participantRead?: readonly string[];
-    collections?: Record<string, AuthoredCollectionConfig>;
-}
-/** What this audience may CHANGE, per collection it draws.
- *
- *  The `collections` config is the PROMOTED one where there is one: at publish
- *  the rules run against what deploy staged, so projecting the manifest's
- *  would advertise transitions the live rules deny. */
-export declare function tierWrites(authored: AuthoredApp, audience: Exclude<ViewAudience, "public">, cids: string[], promoted: PromotedRuleConfig): ProjectedViewWrite[];
-/** What this audience may READ, and how to query for it.
- *
- *  A collection with no scope is dropped rather than published as unreachable:
- *  the gate has already refused the declaration, so reaching here with one is
- *  a programming error, and a page that queries it is denied. */
-export declare function tierViews(authored: AuthoredApp, audience: Exclude<ViewAudience, "public">, views: NormalizedView[], participantRead: readonly string[]): {
-    id: string;
-    collections: ProjectedViewCollection[];
-}[];
-export declare function projectAppViews(authored: AuthoredApp, stamp: PublishStamp, promoted?: PromotedRuleConfig): AppViewTier[];
-/** The document a tier's projection is published at. Beside the views
- *  themselves, under one `match` — see `firestore.rules`. */
-export declare const viewConfigDocId: (stage: "live" | "staged") => string;