@formfeed/devkit 0.1.0 → 0.3.0

package/types/lib/project.d.ts

@@ -1,4 +1,4 @@
-import type { EngineId, TemplateKind, TemplateSettings } from '@formfeed/engine';
+import { type EngineId, type OfficeKind, type TemplateKind, type TemplateSettings } from '@formfeed/engine';
 import type { TemplateVersion } from '@formfeed/sdk';
 import type { Project } from './project-config.js';
 /**
@@ -9,15 +9,29 @@ import type { Project } from './project-config.js';
  */
 export interface TemplateMeta {
     name: string;
-    kind: TemplateKind;
+    /** An HTML kind, or `docx`/`pptx` for Word and PowerPoint templates. */
+    kind: TemplateKind | OfficeKind;
     engine: EngineId;
     description?: string | null;
     tags?: string[];
 }
+/**
+ * The document of a Word or PowerPoint template (spec 22 §7): `template.docx` or `template.pptx`
+ * instead of `template.html`. Such a folder has no markup, style, head, header, footer or partials.
+ */
+export interface LocalOfficeFile {
+    format: OfficeKind;
+    path: string;
+    bytes: Uint8Array;
+    sha256: string;
+}
 export interface LocalTemplate {
     slug: string;
     dir: string;
     meta: TemplateMeta;
+    /** The Word or PowerPoint document; `null` for HTML templates. */
+    file: LocalOfficeFile | null;
+    /** Empty for Word and PowerPoint templates. */
     html: string;
     css: string;
     head: string;
@@ -27,6 +41,15 @@ export interface LocalTemplate {
     dataSets: Record<string, unknown>;
     dataSchema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    /** Partials the template includes, read from the project's folder; they travel with the version. */
+    partials: Record<string, string>;
+    /** Included names without a file; `validate` reports them and `push` refuses them. */
+    missingPartials: string[];
+    /**
+     * Included names that are shared partials of the organisation (recorded in the state by
+     * `formfeed partials pull|push`). They resolve live on the server, so they stay out of `partials`.
+     */
+    sharedPartials: string[];
 }
 export interface TemplateState {
     /** Checksum of the remote version the folder was pulled from or pushed as. */
@@ -35,11 +58,26 @@ export interface TemplateState {
     status: string;
     /** Hash of the local files at that moment; a different hash means local edits. */
     contentHash: string;
+    /** Word and PowerPoint templates: the document's SHA-256, so `push` uploads it only when it changed. */
+    fileSha256?: string;
+    syncedAt: string;
+}
+/** A shared partial of the organisation as last pulled or pushed (spec 18 §8). */
+export interface SharedPartialState {
+    /** The remote version; `partials push` sends it as `base_version`. */
+    version: number;
+    engine: EngineId;
+    /** Hash of the local file at that moment; a different hash means local edits. */
+    contentHash: string;
     syncedAt: string;
 }
 export interface ProjectState {
     templates: Record<string, TemplateState>;
+    /** Shared partials by name; they live in `partialsDir` as `<name>.html`. */
+    sharedPartials?: Record<string, SharedPartialState>;
 }
+/** The file a template folder is built around, by kind. */
+export declare const templateFileName: (kind: TemplateKind | string) => string;
 export declare function listTemplateSlugs(project: Project): string[];
 export declare function templateDir(project: Project, slug: string): string;
 export declare function readTemplate(project: Project, slug: string): LocalTemplate;
@@ -48,19 +86,43 @@ export declare function defaultData(tpl: LocalTemplate, name?: string): {
     name: string;
     data: unknown;
 };
+/**
+ * Writes a pulled version into the template folder. A Word or PowerPoint template needs its
+ * document as `file`; the folder then holds `template.<kind>` and none of the HTML files, so a
+ * template whose kind changed leaves nothing behind that would be read as its source.
+ */
 export declare function writeTemplate(project: Project, slug: string, meta: TemplateMeta, version: Pick<TemplateVersion, 'html' | 'css' | 'head' | 'settings' | 'sample_data' | 'data_schema' | 'i18n'> & {
     data_sets?: Record<string, unknown> | null;
-}): string;
+    partials?: Record<string, string> | null;
+}, file?: Uint8Array): string;
+/**
+ * Writes the partials of a pulled version into the project's folder (`name` or `name.html`, the
+ * two spellings `partialResolver` reads). Returns the files whose content changed, so `pull` can
+ * say that a partial shared with another template was replaced.
+ */
+export declare function writePartials(project: Project, partials: Record<string, string> | null): string[];
+/**
+ * Fields of a push request besides the document: what the API's version create takes for a Word or
+ * PowerPoint template. The document itself travels as the multipart `file`.
+ */
+export declare function officeVersionPayload(tpl: LocalTemplate): {
+    settings: Record<string, unknown>;
+    sample_data: Record<string, unknown>;
+    data_sets: Record<string, unknown>;
+    data_schema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+};
 /** Files of a push request: what the API's TemplateVersionCreate takes. */
 export declare function versionPayload(tpl: LocalTemplate): {
-    html: string;
-    css: string;
-    head: string;
+    partials?: Record<string, string> | undefined;
     settings: Record<string, unknown>;
     sample_data: Record<string, unknown>;
     data_sets: Record<string, unknown>;
     data_schema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    html: string;
+    css: string;
+    head: string;
 };
 /** Stable hash of the local files; compared with the state to detect local edits. */
 export declare function contentHash(tpl: LocalTemplate): string;
@@ -68,5 +130,19 @@ export declare function readState(project: Project): ProjectState;
 export declare function writeState(project: Project, state: ProjectState): void;
 export declare function recordSync(project: Project, slug: string, version: Pick<TemplateVersion, 'checksum' | 'number' | 'status'>, tpl: LocalTemplate): void;
 export declare function titleFromSlug(slug: string): string;
-/** Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`). */
+/**
+ * Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`).
+ * A name that matches a shared partial of the state only after normalisation (`Letterhead.j2` for
+ * `letterhead`) falls back to that partial's file, the way the server matches shared partials.
+ */
 export declare function partialResolver(project: Project): (name: string) => string | undefined;
+/** Where a shared partial lives locally: `<partialsDir>/<name>.html`. */
+export declare function sharedPartialPath(project: Project, name: string): string;
+/** Normalised names of the shared partials recorded for one engine; other engines' partials never resolve. */
+export declare function sharedPartialNames(project: Project, engine: EngineId): Set<string>;
+export declare const partialContentHash: (source: string) => string;
+/** Records a pulled or pushed shared partial with the remote version and the hash of `source`. */
+export declare function recordSharedPartial(project: Project, name: string, remote: {
+    version: number;
+    engine: EngineId;
+}, source: string): void;

package/types/lib/redact.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Shape-keeping redaction of render data (spec 20 §3.3), for `formfeed renders pull --redact`.
+ *
+ * Strings become placeholders of the same length that keep the character classes: upper-case
+ * letters become `A`, other letters `a`, digits `0`, and everything else (spaces, `@`, `.`, `-`)
+ * stays, so `jane@mail.test` becomes `aaaa@aaaa.aaaa` and `DE00 0000` becomes `AA00 0000`. Numbers,
+ * booleans and null are kept: they are usually what made the render go wrong, and they rarely
+ * identify a person. Arrays and objects keep their keys and lengths.
+ *
+ * Paths select what is redacted, from the root of the data: dotted segments (`customer.email`),
+ * `*` for any one key or array item (`customer.*`), and `[]` for every item of an array
+ * (`items[].name`, the same as `items.*.name`). A path that ends on an object or array redacts
+ * everything below it. Without paths (or with an empty list) the whole data set is redacted.
+ */
+export declare function redactData<T>(value: T, paths?: readonly string[]): T;
+/** A placeholder of the same length with the character classes of `text` kept. */
+export declare function redactString(text: string): string;
+/** `items[].name` → `['items', '*', 'name']`; `lines[0].qty` → `['lines', '0', 'qty']`. */
+export declare function parseRedactPath(path: string): string[];

package/types/lib/redact.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shape-keeping redaction of render data (spec 20 §3.3), for `formfeed renders pull --redact`.
+ *
+ * Strings become placeholders of the same length that keep the character classes: upper-case
+ * letters become `A`, other letters `a`, digits `0`, and everything else (spaces, `@`, `.`, `-`)
+ * stays, so `jane@mail.test` becomes `aaaa@aaaa.aaaa` and `DE00 0000` becomes `AA00 0000`. Numbers,
+ * booleans and null are kept: they are usually what made the render go wrong, and they rarely
+ * identify a person. Arrays and objects keep their keys and lengths.
+ *
+ * Paths select what is redacted, from the root of the data: dotted segments (`customer.email`),
+ * `*` for any one key or array item (`customer.*`), and `[]` for every item of an array
+ * (`items[].name`, the same as `items.*.name`). A path that ends on an object or array redacts
+ * everything below it. Without paths (or with an empty list) the whole data set is redacted.
+ */
+export declare function redactData<T>(value: T, paths?: readonly string[]): T;
+/** A placeholder of the same length with the character classes of `text` kept. */
+export declare function redactString(text: string): string;
+/** `items[].name` → `['items', '*', 'name']`; `lines[0].qty` → `['lines', '0', 'qty']`. */
+export declare function parseRedactPath(path: string): string[];

package/types/lib/types/emit-python.d.cts

@@ -0,0 +1,6 @@
+import { type TemplateTypes } from './model.cjs';
+/**
+ * `formfeed_templates.py`: a TypedDict per template and `typed(client)`, whose `renders.create`
+ * overloads check `data` for the known slugs and fall back to the plain signature otherwise.
+ */
+export declare function emitPython(templates: TemplateTypes[]): string;

package/types/lib/types/emit-python.d.ts

@@ -0,0 +1,6 @@
+import { type TemplateTypes } from './model.js';
+/**
+ * `formfeed_templates.py`: a TypedDict per template and `typed(client)`, whose `renders.create`
+ * overloads check `data` for the known slugs and fall back to the plain signature otherwise.
+ */
+export declare function emitPython(templates: TemplateTypes[]): string;

package/types/lib/types/emit-ts.d.cts

@@ -0,0 +1,10 @@
+import { type TemplateTypes } from './model.cjs';
+export interface TypeScriptOptions {
+    /** The module the generated file augments; `@formfeed/sdk` for customers. */
+    sdkModule?: string;
+}
+/**
+ * `formfeed.d.ts`: one data type per template plus the augmentation of `FormfeedTemplates`, which
+ * makes `renders.create({ template: 'invoice', data })` check `data` against `InvoiceData`.
+ */
+export declare function emitTypeScript(templates: TemplateTypes[], options?: TypeScriptOptions): string;

package/types/lib/types/emit-ts.d.ts

@@ -0,0 +1,10 @@
+import { type TemplateTypes } from './model.js';
+export interface TypeScriptOptions {
+    /** The module the generated file augments; `@formfeed/sdk` for customers. */
+    sdkModule?: string;
+}
+/**
+ * `formfeed.d.ts`: one data type per template plus the augmentation of `FormfeedTemplates`, which
+ * makes `renders.create({ template: 'invoice', data })` check `data` against `InvoiceData`.
+ */
+export declare function emitTypeScript(templates: TemplateTypes[], options?: TypeScriptOptions): string;

package/types/lib/types/index.d.cts

@@ -0,0 +1,15 @@
+import type { LocalTemplate } from '../project.cjs';
+import { type TypeScriptOptions } from './emit-ts.cjs';
+import { type TypeSource } from './model.cjs';
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/**
+ * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
+ * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
+ */
+export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.cjs';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.cjs';
+export type { TypeScriptOptions } from './emit-ts.cjs';

package/types/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+import type { LocalTemplate } from '../project.js';
+import { type TypeScriptOptions } from './emit-ts.js';
+import { type TypeSource } from './model.js';
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/**
+ * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
+ * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
+ */
+export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.js';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.js';
+export type { TypeScriptOptions } from './emit-ts.js';

package/types/lib/types/model.d.cts

@@ -0,0 +1,81 @@
+/**
+ * The language-neutral model `formfeed types` emits from (spec 19 §2.4): each template's data schema
+ * becomes a tree of type nodes plus the named objects it refers to, so the TypeScript and Python
+ * emitters share one reading of JSON Schema and differ only in spelling.
+ */
+export type TypeNode = {
+    kind: 'unknown';
+    note?: string;
+} | {
+    kind: 'never';
+} | {
+    kind: 'primitive';
+    name: 'string' | 'number' | 'integer' | 'boolean' | 'null';
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'array';
+    items: TypeNode;
+} | {
+    kind: 'record';
+    values: TypeNode;
+} | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'union';
+    members: TypeNode[];
+} | {
+    kind: 'intersection';
+    members: TypeNode[];
+};
+export interface Field {
+    key: string;
+    type: TypeNode;
+    required: boolean;
+    doc: string[];
+}
+export interface NamedObject {
+    name: string;
+    doc: string[];
+    fields: Field[];
+    /** Type of properties the schema does not list, when `additionalProperties` is a schema. */
+    extra: TypeNode | null;
+}
+/** Where a template's schema came from; the header of the generated file says it per template. */
+export type SchemaOrigin = 'local' | 'stored' | 'inferred';
+export interface TypeSource {
+    slug: string;
+    schema: Record<string, unknown>;
+    origin: SchemaOrigin;
+    /** The version the schema belongs to, for the header. */
+    version?: number | null;
+    channel?: string | null;
+}
+export interface TemplateTypes {
+    slug: string;
+    origin: SchemaOrigin;
+    version: number | null;
+    channel: string | null;
+    /** The name the data type is exported under (`InvoiceData`). */
+    rootName: string;
+    /** The data type; a `ref` to `rootName` when the schema is an object. */
+    root: TypeNode;
+    /** Named objects in the order they were first met, the root first. */
+    objects: NamedObject[];
+}
+export declare function pascalCase(text: string): string;
+/** `items` → `Item`, `addresses` → `Address`, `entries` → `Entry`; null when the word is not a plural. */
+export declare function singular(word: string): string | null;
+/** Names already handed out in one generated file; a clash gets a number. */
+export declare class NameRegistry {
+    private readonly used;
+    constructor(reserved?: Iterable<string>);
+    claim(wanted: string): string;
+}
+/** An inferred schema knows which fields the sample had, not which the template needs: all optional. */
+export declare function relaxRequired(schema: unknown): unknown;
+/** Builds the model for a set of templates; names are unique across the whole file. */
+export declare function buildTypes(sources: TypeSource[], reserved?: Iterable<string>): TemplateTypes[];
+export declare function originNote(t: Pick<TemplateTypes, 'origin' | 'version' | 'channel'>): string;

package/types/lib/types/model.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The language-neutral model `formfeed types` emits from (spec 19 §2.4): each template's data schema
+ * becomes a tree of type nodes plus the named objects it refers to, so the TypeScript and Python
+ * emitters share one reading of JSON Schema and differ only in spelling.
+ */
+export type TypeNode = {
+    kind: 'unknown';
+    note?: string;
+} | {
+    kind: 'never';
+} | {
+    kind: 'primitive';
+    name: 'string' | 'number' | 'integer' | 'boolean' | 'null';
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'array';
+    items: TypeNode;
+} | {
+    kind: 'record';
+    values: TypeNode;
+} | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'union';
+    members: TypeNode[];
+} | {
+    kind: 'intersection';
+    members: TypeNode[];
+};
+export interface Field {
+    key: string;
+    type: TypeNode;
+    required: boolean;
+    doc: string[];
+}
+export interface NamedObject {
+    name: string;
+    doc: string[];
+    fields: Field[];
+    /** Type of properties the schema does not list, when `additionalProperties` is a schema. */
+    extra: TypeNode | null;
+}
+/** Where a template's schema came from; the header of the generated file says it per template. */
+export type SchemaOrigin = 'local' | 'stored' | 'inferred';
+export interface TypeSource {
+    slug: string;
+    schema: Record<string, unknown>;
+    origin: SchemaOrigin;
+    /** The version the schema belongs to, for the header. */
+    version?: number | null;
+    channel?: string | null;
+}
+export interface TemplateTypes {
+    slug: string;
+    origin: SchemaOrigin;
+    version: number | null;
+    channel: string | null;
+    /** The name the data type is exported under (`InvoiceData`). */
+    rootName: string;
+    /** The data type; a `ref` to `rootName` when the schema is an object. */
+    root: TypeNode;
+    /** Named objects in the order they were first met, the root first. */
+    objects: NamedObject[];
+}
+export declare function pascalCase(text: string): string;
+/** `items` → `Item`, `addresses` → `Address`, `entries` → `Entry`; null when the word is not a plural. */
+export declare function singular(word: string): string | null;
+/** Names already handed out in one generated file; a clash gets a number. */
+export declare class NameRegistry {
+    private readonly used;
+    constructor(reserved?: Iterable<string>);
+    claim(wanted: string): string;
+}
+/** An inferred schema knows which fields the sample had, not which the template needs: all optional. */
+export declare function relaxRequired(schema: unknown): unknown;
+/** Builds the model for a set of templates; names are unique across the whole file. */
+export declare function buildTypes(sources: TypeSource[], reserved?: Iterable<string>): TemplateTypes[];
+export declare function originNote(t: Pick<TemplateTypes, 'origin' | 'version' | 'channel'>): string;