@freema/drobek-modules 0.3.3

package/dist/migrations/core/0025_app_asset_snapshots.sql

@@ -0,0 +1,28 @@
+-- NSO-362: assets honour publish. `app_assets` becomes the draft (what the
+-- preview host serves); `app_version_assets` holds the set a publish froze for
+-- a version (what the production host serves), `app_versions.assets_frozen_at`
+-- marks a version that has one. Upgrade: the assets of every published app are
+-- frozen as its live version's set, so nothing a public URL serves today
+-- disappears; they stay the draft too.
+CREATE TABLE "app_version_assets" (
+	"version_id" text NOT NULL,
+	"app_id" text NOT NULL,
+	"name" text NOT NULL,
+	"content_type" text NOT NULL,
+	"size" bigint NOT NULL,
+	"sha256" text NOT NULL,
+	"storage_key" text NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "app_version_assets_version_id_name_pk" PRIMARY KEY("version_id","name")
+);
+--> statement-breakpoint
+ALTER TABLE "app_versions" ADD COLUMN "assets_frozen_at" timestamp;--> statement-breakpoint
+ALTER TABLE "app_version_assets" ADD CONSTRAINT "app_version_assets_version_id_app_versions_id_fk" FOREIGN KEY ("version_id") REFERENCES "public"."app_versions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "app_version_assets" ADD CONSTRAINT "app_version_assets_app_id_apps_id_fk" FOREIGN KEY ("app_id") REFERENCES "public"."apps"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "app_version_assets_app_idx" ON "app_version_assets" USING btree ("app_id");--> statement-breakpoint
+INSERT INTO "app_version_assets" ("version_id", "app_id", "name", "content_type", "size", "sha256", "storage_key", "updated_at")
+SELECT a."published_version_id", aa."app_id", aa."name", aa."content_type", aa."size", aa."sha256", aa."storage_key", aa."updated_at"
+FROM "app_assets" aa JOIN "apps" a ON a."id" = aa."app_id"
+WHERE a."published_version_id" IS NOT NULL;--> statement-breakpoint
+UPDATE "app_versions" SET "assets_frozen_at" = now()
+WHERE "id" IN (SELECT "published_version_id" FROM "apps" WHERE "published_version_id" IS NOT NULL);

package/dist/migrations/core/0026_publish_approval.sql

@@ -0,0 +1,13 @@
+-- NSO-366: PUBLISH_APPROVAL=approval — a super-admin decides per workspace
+-- whether it may publish. `publish_approved_at` null = not approved; the
+-- approval request columns dedupe the operator e-mail. Upgrade: every
+-- workspace that already has a published app is approved now, so turning
+-- approval on never takes the next publish of a live app away.
+ALTER TABLE "workspaces" ADD COLUMN "publish_approved_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD COLUMN "publish_approved_by" text;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD COLUMN "publish_approval_requested_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD COLUMN "publish_approval_requested_by" text;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD CONSTRAINT "workspaces_publish_approved_by_users_id_fk" FOREIGN KEY ("publish_approved_by") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD CONSTRAINT "workspaces_publish_approval_requested_by_users_id_fk" FOREIGN KEY ("publish_approval_requested_by") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+UPDATE "workspaces" SET "publish_approved_at" = now()
+WHERE "id" IN (SELECT "workspace_id" FROM "apps" WHERE "published_version_id" IS NOT NULL AND "deleted_at" IS NULL);

package/dist/migrations/core/0027_publish_block.sql

@@ -0,0 +1,6 @@
+-- NSO-366: a super-admin can turn publishing off for a workspace, in every
+-- PUBLISH_APPROVAL mode. Blocked = publish_blocked_at set; allowed =
+-- publish_approved_at set (0026); neither = the server mode decides.
+ALTER TABLE "workspaces" ADD COLUMN "publish_blocked_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD COLUMN "publish_blocked_by" text;--> statement-breakpoint
+ALTER TABLE "workspaces" ADD CONSTRAINT "workspaces_publish_blocked_by_users_id_fk" FOREIGN KEY ("publish_blocked_by") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;

package/dist/migrations/core/meta/_journal.json

@@ -0,0 +1,167 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1782985986575,
+      "tag": "0000_dusty_scarecrow",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1783043106616,
+      "tag": "0001_busy_orphan",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1783067845061,
+      "tag": "0002_odd_alex_power",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1783096383394,
+      "tag": "0003_nosy_shatterstar",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1783125113132,
+      "tag": "0004_nice_ben_parker",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1783143918577,
+      "tag": "0005_panoramic_bill_hollister",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1783151896848,
+      "tag": "0006_outgoing_ricochet",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1790132000000,
+      "tag": "0007_app_versions",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1790146977226,
+      "tag": "0008_user_bound_tokens",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1790149105340,
+      "tag": "0009_app_name",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1790152014046,
+      "tag": "0010_apps_origin",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1790162052842,
+      "tag": "0011_modules",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "7",
+      "when": 1790175801064,
+      "tag": "0012_data_module_tables",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1790192202963,
+      "tag": "0014_get_logs",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "7",
+      "when": 1790194823940,
+      "tag": "0016_apps_slug_release",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1790194890971,
+      "tag": "0018_custom_domains",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1790196335795,
+      "tag": "0021_abuse_reports",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1790432415711,
+      "tag": "0022_gallery",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1790432800000,
+      "tag": "0023_workspace_modules",
+      "breakpoints": true
+    },
+    {
+      "idx": 24,
+      "version": "7",
+      "when": 1790433136356,
+      "tag": "0024_app_assets",
+      "breakpoints": true
+    },
+    {
+      "idx": 25,
+      "version": "7",
+      "when": 1790437501780,
+      "tag": "0025_app_asset_snapshots",
+      "breakpoints": true
+    },
+    {
+      "idx": 26,
+      "version": "7",
+      "when": 1790493019726,
+      "tag": "0026_publish_approval",
+      "breakpoints": true
+    },
+    {
+      "idx": 27,
+      "version": "7",
+      "when": 1790496410618,
+      "tag": "0027_publish_block",
+      "breakpoints": true
+    }
+  ]
+}

package/dist/testing.d.ts

@@ -0,0 +1,269 @@
+import { AnyModule, SdkBundle, ModuleContext, MailEnvelope, Principal, EndUserCallbackResult, HookApp, DB, Logger, MailGuard } from './index.js';
+import 'node:stream';
+import 'drizzle-orm/postgres-js';
+import 'zod';
+
+/** One skill as the checker sees it (a module's `skill.markdown`, or a general `skills/<name>/SKILL.md`). */
+interface SkillSource {
+    name: string;
+    kind: 'module' | 'general';
+    useWhen: string;
+    /** The markdown skill_info returns (a general skill: without its frontmatter). */
+    content: string;
+    /** The SKILL.md as named in the issues (e.g. `SKILL.md`, `modules/auth/SKILL.md`). */
+    file: string;
+    /** The file's full text (frontmatter included). */
+    fileText: string;
+    module?: AnyModule;
+}
+/** One finding of `checkSkill` / `checkSkillSources`. */
+interface SkillIssue {
+    skill: string;
+    /** The SKILL.md (see SkillSource.file). */
+    file: string;
+    /** 0-based index of the code block in the file; -1 when the issue is not about one block. */
+    block: number;
+    /** 1-based line in the SKILL.md (0 when the issue concerns the whole file). */
+    line: number;
+    message: string;
+}
+/** `SKILL.md:12 (skill "erp", code block #2): message` */
+declare function formatSkillIssue(p: SkillIssue): string;
+
+/**
+ * `checkSkill(module)` (NSO-349) — the SKILL.md gate the built-in modules
+ * pass, for any module: a module author runs it in the module's own tests
+ * (`@drobek/modules/testing`), the repo gate (packages/skills-check) runs
+ * `checkSkillSources` over the built-in modules + the general skills.
+ *
+ *  - the format: the five sections in order, ≤ 150 lines, a one-sentence
+ *    "use when", working code first, only real error codes (the core
+ *    catalogue + the module's own `errors`), present tense (format.ts);
+ *  - the code: every fenced block compiled with drobek's compiler and
+ *    typechecked against the sdk.d.ts of the module (+ `modules`), `ts api`
+ *    blocks mutually assignable to the real SDK, configure_module payloads
+ *    against the module's schema (examples.ts).
+ */
+
+interface CheckSkillOptions {
+    /**
+     * Other modules the skill's examples use next to this one (e.g. the
+     * built-in `auth` module for `drobek.auth`): their SDK is composed in and
+     * their configure_module payloads are checked. Default: none.
+     */
+    modules?: AnyModule[];
+    /** The SKILL.md as named in the issues (default `SKILL.md`). */
+    file?: string;
+    /**
+     * The directory whose node_modules resolve the examples' bare imports
+     * (`react` → @types/react, …); default: the working directory. An import
+     * that does not resolve is typed `any`.
+     */
+    root?: string;
+}
+interface CheckSkillSourcesOptions {
+    /** The SDK bundle of `modules` (built when omitted). */
+    sdk?: SdkBundle;
+    /** See CheckSkillOptions.root. */
+    root?: string;
+}
+/** The error codes a skill may name: the core catalogue + its module's `errors` (a general skill: every module's). */
+declare function knownErrorCodes(src: SkillSource, modules: AnyModule[]): Set<string>;
+/** Format + code issues of `skills` on a server running `modules` (every module skill's module must be among them). */
+declare function checkSkillSources(skills: SkillSource[], modules: AnyModule[], opts?: CheckSkillSourcesOptions): Promise<SkillIssue[]>;
+/** The skill of one module as skill_info serves it. */
+declare function moduleSkillSource(module: AnyModule, file?: string): SkillSource;
+/**
+ * Check a module's skill (`defineModule({ skill })`) the way drobek checks
+ * its built-in modules. `[]` = it passes.
+ *
+ *   const issues = await checkSkill(erp);
+ *   expect(issues.map(formatSkillIssue)).toEqual([]);
+ */
+declare function checkSkill(module: AnyModule, opts?: CheckSkillOptions): Promise<SkillIssue[]>;
+
+interface ExamplesOptions {
+    /** The SDK bundle of `modules` (built when omitted). */
+    sdk?: SdkBundle;
+    /** The directory whose node_modules resolve the examples' bare imports (default: the working directory). */
+    root?: string;
+}
+interface ExamplesReport {
+    problems: SkillIssue[];
+    counts: {
+        blocks: number;
+        compiled: number;
+        typechecked: number;
+        apiChecked: number;
+        configChecked: number;
+    };
+}
+/**
+ * Compile and typecheck every code block of `skills` against the SDK of
+ * `modules` (the server's sdk.d.ts + the inline declarations).
+ */
+declare function checkExamples(skills: SkillSource[], modules: AnyModule[], opts?: ExamplesOptions): Promise<ExamplesReport>;
+
+declare const SKILL_SECTIONS: readonly ["1. When to use", "2. Minimal working code", "3. API and types", "4. Rules and limits", "5. Errors → fix"];
+declare const SKILL_MAX_LINES = 150;
+/**
+ * The format issues of one skill. `knownCodes`: the error codes the skill may
+ * name in "Errors → fix" (the core catalogue + the module's own `errors`).
+ */
+declare function skillFormatIssues(src: SkillSource, knownCodes: ReadonlySet<string>): SkillIssue[];
+
+/**
+ * A tiny Markdown reader for the skills: fenced code blocks (with their info
+ * string) and `##` headings. Skills are plain CommonMark written by us, so a
+ * line scanner is enough — no dependency.
+ */
+interface CodeBlock {
+    /** First word of the info string (`tsx`, `json`, `html`, …); '' when none. */
+    lang: string;
+    /** The rest of the info string (`api`, `drobek.json`, …). */
+    meta: string;
+    code: string;
+    /** 1-based line of the opening fence. */
+    line: number;
+    /** 0-based index among the file's code blocks. */
+    index: number;
+    /** The `##` heading the block sits under ('' before the first). */
+    section: string;
+}
+interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+declare function codeBlocks(markdown: string): CodeBlock[];
+/** Every ATX heading outside code blocks. */
+declare function headings(markdown: string): Heading[];
+/** The text between the `##` heading that starts with `prefix` and the next `##` (fences included). */
+declare function sectionText(markdown: string, prefix: string): string;
+/** The markdown without its fenced code blocks (the prose an agent reads). */
+declare function proseOf(markdown: string): string;
+
+/**
+ * The folder of drobek's core migrations (journal `__drizzle_migrations_core`):
+ * apply it before a module's own migrations, whose tables reference
+ * `apps(id)`. The published package ships a copy (`dist/migrations/core`);
+ * in the drobek repository it is `packages/db/drizzle/migrations`.
+ */
+declare function coreMigrationsDir(): string;
+/**
+ * A workspace + an app in a database with the core migrations applied — the
+ * `app` to pass to createModuleTestContext (module rows reference its id).
+ */
+declare function createTestApp(db: unknown, opts?: {
+    slug?: string;
+}): Promise<HookApp>;
+interface ModuleTestOptions {
+    /** A partial config (merged over configDefaults, then validated). */
+    config?: Record<string, unknown>;
+    principal?: Principal;
+    /** Secret name → plaintext. */
+    secrets?: Record<string, string>;
+    /** Limit overrides (the rest come from the module's defaults). */
+    limits?: Record<string, number>;
+    app?: Partial<HookApp>;
+    db?: DB;
+    log?: Logger;
+    /** The app host the requests come from (default `http://test--preview.apps.localhost`). */
+    origin?: string;
+    now?: () => number;
+    /** The app owners' addresses (`{ appOwners: true }` recipients; default none). */
+    owners?: string[];
+    /**
+     * The operator-wide e-mail guard core runs around every `ctx.email.send`
+     * (e.g. `memoryMailGuard(...)`): pass one to test how the module behaves
+     * while module e-mail is paused. Default: no guard.
+     */
+    mailGuard?: MailGuard;
+    /**
+     * Slot → the contributions `ctx.contributions(slot)` returns (as the
+     * slot's schema would have parsed them; default: none — `[]`). A slot
+     * host's `compose` runs with them first, as at server start.
+     */
+    contributions?: Record<string, unknown[]>;
+}
+/** One request to the module's `endUsers.callback` (the dashboard-host IdP callback). */
+interface TestCallbackInit {
+    provider: string;
+    method?: 'GET' | 'POST';
+    query?: Record<string, string>;
+    body?: Record<string, string> | null;
+    /** Default `127.0.0.1`; `null` = no resolved client IP. */
+    clientIp?: string | null;
+}
+interface TestRequestInit {
+    /** A JSON body. */
+    body?: unknown;
+    /** A raw body instead (set its `content-type` in `headers`), e.g. multipart/form-data. */
+    rawBody?: Buffer | string;
+    /** A `bodyTypes: ['file']` route streams `rawBody` in chunks of this many bytes (default 64 KiB). */
+    chunkSize?: number;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Default `127.0.0.1`; `null` = no resolved client IP (per-IP limits are skipped). */
+    clientIp?: string | null;
+}
+interface TestResponse {
+    status: number;
+    headers: Record<string, string>;
+    /** Parsed JSON (or the raw text when the body is not JSON). */
+    body: unknown;
+    /** The raw response bytes (a streamed body is collected). */
+    bytes: Buffer;
+    /** Request body bytes a streaming (`file`) route pulled before it stopped. */
+    bodyBytesRead: number;
+}
+interface ModuleTestContext {
+    ctx: ModuleContext<any>;
+    /**
+     * Run `method path` through the production pipeline. SDK header + same
+     * Origin are sent by default. Rejects — where production answers
+     * `500 internal_error` — when the handler throws something other than a
+     * ModuleError, or a ModuleError whose code is neither a core code nor in
+     * the module's `errors`.
+     */
+    request(method: string, path: string, init?: TestRequestInit): Promise<TestResponse>;
+    /** Audit rows the module wrote (`<module>.<action>`). */
+    audits: {
+        action: string;
+        meta: Record<string, unknown>;
+    }[];
+    /**
+     * E-mails the module sent (resolved recipients, one entry per send). When
+     * the module under test is the mail authority (`mail`), its own `prepare`
+     * runs first (limits, envelope) exactly as core runs it.
+     */
+    emails: ({
+        to: string[];
+        subject: string;
+        text: string;
+        kind: 'sign_in' | 'notification';
+    } & MailEnvelope)[];
+    /** Change who is calling. */
+    setPrincipal(principal: Principal): void;
+    /**
+     * Run the module's `confirmRequired(before, after, context)` the way
+     * configure_module does — both configs merged over configDefaults and
+     * validated, the context naming the test app and `db` ([] without a
+     * confirmRequired).
+     */
+    confirm(before: Record<string, unknown>, after: Record<string, unknown>): Promise<string[]>;
+    /**
+     * Run the module's `endUsers.callback` the way core runs it for
+     * `/__drobek/auth/callback/:provider` on the dashboard host: the test app
+     * is the only live app (`services.app(id)` answers it for its id, null for
+     * any other), with the test config, secrets, limits and audits; the rate
+     * limiter shares the test clock. Rejects when the module has no callback.
+     */
+    endUserCallback(init: TestCallbackInit): Promise<EndUserCallbackResult>;
+    /** The module as the test runs it (composed from `contributions` when it hosts slots). */
+    module: AnyModule;
+}
+declare function createModuleTestContext(declared: AnyModule, opts?: ModuleTestOptions): ModuleTestContext;
+
+export { SKILL_MAX_LINES, SKILL_SECTIONS, checkExamples, checkSkill, checkSkillSources, codeBlocks, coreMigrationsDir, createModuleTestContext, createTestApp, formatSkillIssue, headings, knownErrorCodes, moduleSkillSource, proseOf, sectionText, skillFormatIssues };
+export type { CheckSkillOptions, CheckSkillSourcesOptions, CodeBlock, ExamplesOptions, ExamplesReport, Heading, ModuleTestContext, ModuleTestOptions, SkillIssue, SkillSource, TestCallbackInit, TestRequestInit, TestResponse };