@contentrain/types - npm Package Compare versions

Comparing version 0.9.0 to 1.0.2

dist/index.d.mts

@@ -82,2 +82,18 @@ //#region src/provider.d.ts
   timestamp: string;
+  /**
+   * What the provider did with the branch. Providers that own the merge
+   * decision (a local worktree honouring the project's `workflow` setting)
+   * report it here; providers that hand the branch off to an external
+   * orchestrator leave it undefined, and the caller treats that as
+   * `pending-review`.
+   */
+  workflowAction?: 'auto-merged' | 'pending-review';
+  /**
+   * Selective-sync bookkeeping — which files were copied into the developer's
+   * working tree and which were skipped because of local edits. Only
+   * providers backed by a local worktree populate it.
+   */
+  sync?: SyncResult;
+  /** Non-fatal problem encountered while completing the write. */
+  warning?: string;
 }
@@ -105,2 +121,17 @@ /**
   base?: string;
+  /**
+   * Describes the operation that produced these changes. A provider that
+   * regenerates `.contentrain/context.json` itself (the local worktree flow
+   * does, after merge, single-threaded) uses it; others ignore it. It is
+   * never committed on the feature branch — context.json embeds timestamps,
+   * so two branches forked from the same commit would always conflict on it.
+   */
+  context?: {
+    tool: string;
+    model: string;
+    locale?: string;
+    entries?: string[];
+  };
+  /** Override the project's configured workflow for this write. */
+  workflowOverride?: 'auto-merge' | 'review';
 }
@@ -226,2 +257,8 @@ /**
  */
+/** Result of {@link RepoProvider.checkWriteReadiness}. */
+interface WriteReadiness {
+  blocked: boolean;
+  /** Human-readable reason, present when `blocked`. */
+  message?: string;
+}
 interface RepoProvider extends RepoReader, RepoWriter {
@@ -248,2 +285,14 @@ readonly capabilities: ProviderCapabilities;
   readonly media?: MediaProvider;
+  /**
+   * Whether the provider will accept a write right now.
+   *
+   * A local worktree accumulates unmerged `cr/*` branches and eventually has
+   * to refuse new ones; a hosted provider manages that server-side. Asking the
+   * provider keeps the tool layer out of the business of counting git branches
+   * — it previously reached through an `instanceof` check to a `projectRoot`
+   * only one implementation has.
+   *
+   * Optional: a provider that omits it is always ready.
+   */
+  checkWriteReadiness?(): Promise<WriteReadiness>;
   listBranches(prefix?: string): Promise<Branch[]>;
@@ -295,2 +344,27 @@ createBranch(name: string, fromRef?: string): Promise<void>;
   description?: string;
+  /**
+   * Human-readable name for this field in an editing UI.
+   *
+   * A plain string is one label for every locale; an object keyed by locale
+   * carries a translation per locale. The union exists now rather than later
+   * because widening `string` to it afterwards would break every consumer
+   * that treats the value as a string.
+   *
+   * Absent means the field name itself is the label — which is why an editor
+   * shows `body_public` and `is_category_hero` today.
+   */
+  label?: string | Record<string, string>;
+  /**
+   * Display position in an editing UI, ascending.
+   *
+   * Fields are stored in canonical alphabetical order, so without this an
+   * editor shows them alphabetically: on a 16-field article model `author`
+   * comes first and `title` fifteenth. Fractional values are allowed so a
+   * field can be inserted between two others without renumbering the rest.
+   *
+   * Fields without one sort after every field that has one, alphabetically
+   * among themselves — so a model that has not been given an order behaves
+   * exactly as it does today.
+   */
+  order?: number;
 }
@@ -304,2 +378,12 @@ type LocaleStrategy = 'file' | 'suffix' | 'directory' | 'none';
   i18n: boolean;
+  /**
+   * Name of the field whose value is shown as an entry's title — in a Studio row,
+   * a picker, a relation reference. Declared, never guessed: a consumer that infers
+   * the title from field order or length picks the icon over the headline.
+   *
+   * Must name a field that exists on this model and whose type can render as text
+   * (see `isTitleFieldType`). Dictionary models have no fields, so their only legal
+   * value is `DICTIONARY_TITLE_FIELD` — the entry key is the title.
+   */
+  title_field: string;
   description?: string;
@@ -369,2 +453,11 @@ fields?: Record<string, FieldDef>;
   updated_by: string;
+  /**
+   * When this entry was last written, ISO 8601 UTC.
+   *
+   * Optional, and deliberately not backfilled. It is a fact about the past,
+   * and an entry written before the field existed has no recoverable value —
+   * a fabricated timestamp would be worse than an absent one, because it
+   * would sort. Absent means unknown; the first write mints the real value.
+   */
+  updated_at?: string;
   approved_by?: string | null;
@@ -471,2 +564,14 @@ version?: string;
 };
+/**
+ * Key order for canonical model JSON — the required keys first, then the optional
+ * ones, then `fields` last so a reader sees the model's identity before scrolling
+ * past its schema.
+ *
+ * This lives here, and only here, because `canonicalStringify` falls back to
+ * alphabetical for any key absent from the order: a forgotten entry does not error,
+ * it silently relocates. `satisfies` catches a key that is not on `ModelDefinition`;
+ * the `keyof` assertion in index.test.ts catches a `ModelDefinition` key missing
+ * from this array. Between them, drift fails `tsc`, which runs on every commit.
+ */
+declare const MODEL_FIELD_ORDER: readonly ["id", "name", "kind", "domain", "i18n", "title_field", "description", "content_path", "locale_strategy", "fields"];
 interface ScaffoldTemplate {
@@ -657,2 +762,37 @@ id: string;
 /**
+ * Resolve a field's label for a locale.
+ *
+ * Falls back in the order a reader would expect: the requested locale, the
+ * default locale, any locale present, then the field name. A field with no
+ * label resolves to its own name, which is what an editor shows today.
+ */
+declare function resolveFieldLabel(fieldName: string, field: Pick<FieldDef, 'label'>, locale?: string, defaultLocale?: string): string;
+/**
+ * Field names in display order.
+ *
+ * Exported so every consumer orders identically instead of each reimplementing
+ * the fallback. Ascending `order`; fields without one come last, alphabetically
+ * among themselves, which is the behaviour a model that has no `order` already
+ * has.
+ */
+declare function orderedFieldNames(fields: Record<string, FieldDef> | undefined): string[];
+/**
+ * The reserved `title_field` value for dictionary models. A dictionary has no
+ * fields — it is a flat key→string map — so there is nothing to point at. Its key
+ * *is* the title, and this names that fact rather than leaving the property blank.
+ * Only dictionaries may use it; on any other kind `title_field` must name a real field.
+ */
+declare const DICTIONARY_TITLE_FIELD = "key";
+/**
+ * Field types whose value can stand in as a human-readable title.
+ *
+ * Narrower than "types that hold a string": `color`, `phone`, `icon`, `select`,
+ * `date`, `datetime`, `relation` and the media types all store strings, but a row
+ * labelled `#ff0000` or `f3a81c09d24e` is exactly the failure this contract exists
+ * to prevent.
+ */
+declare const TITLE_FIELD_TYPES: readonly ["string", "text", "slug", "email", "url", "code", "markdown", "richtext"];
+/** Whether a field of this type may be named as a model's `title_field`. */
+declare function isTitleFieldType(type: FieldType): boolean;
+/**
  * Check a media value's file extension against an `accept` list.
@@ -678,5 +818,5 @@ *
 /** Recursively sort object keys — respects optional fieldOrder for top-level keys */
-declare function sortKeys(obj: unknown, fieldOrder?: string[]): unknown;
+declare function sortKeys(obj: unknown, fieldOrder?: readonly string[]): unknown;
 /** Canonical JSON serialization — deterministic output for stable git diffs */
-declare function canonicalStringify(data: unknown, fieldOrder?: string[]): string;
+declare function canonicalStringify(data: unknown, fieldOrder?: readonly string[]): string;
 /** Generate a 12-character hex entry ID */
@@ -692,3 +832,3 @@ declare function generateEntryId(): string;
 //#endregion
-export { type ApplyPlanInput, AssetEntry, type Branch, CANONICAL_JSON, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, type Commit, type CommitAuthor, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EntryMeta, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GraphNode, LOCALE_PATTERN, LOCAL_CAPABILITIES, LocaleStrategy, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, PATH_PATTERNS, Platform, PolymorphicRelationRef, ProjectGraph, type ProviderCapabilities, type RepoProvider, type RepoReader, type RepoWriter, SECRET_PATTERNS, SLUG_PATTERN, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, StackType, StringContext, SyncResult, ValidationError, ValidationResult, Vocabulary, WorkflowMode, canonicalStringify, detectSecrets, generateEntryId, isMediaType, parseMarkdownFrontmatter, serializeMarkdownFrontmatter, sortKeys, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
+export { type ApplyPlanInput, AssetEntry, type Branch, CANONICAL_JSON, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, type Commit, type CommitAuthor, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, DICTIONARY_TITLE_FIELD, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EntryMeta, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GraphNode, LOCALE_PATTERN, LOCAL_CAPABILITIES, LocaleStrategy, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, PATH_PATTERNS, Platform, PolymorphicRelationRef, ProjectGraph, type ProviderCapabilities, type RepoProvider, type RepoReader, type RepoWriter, SECRET_PATTERNS, SLUG_PATTERN, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, StackType, StringContext, SyncResult, TITLE_FIELD_TYPES, ValidationError, ValidationResult, Vocabulary, WorkflowMode, type WriteReadiness, canonicalStringify, detectSecrets, generateEntryId, isMediaType, isTitleFieldType, orderedFieldNames, parseMarkdownFrontmatter, resolveFieldLabel, serializeMarkdownFrontmatter, sortKeys, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
 //# sourceMappingURL=index.d.mts.map

dist/index.d.mts.map

@@ -1,1 +0,1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provider.ts","../src/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provider.ts","../src/index.ts"],"mappings":"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"}

dist/index.mjs

@@ -58,2 +58,25 @@ //#region src/provider.ts
 };
+/**
+* Key order for canonical model JSON — the required keys first, then the optional
+* ones, then `fields` last so a reader sees the model's identity before scrolling
+* past its schema.
+*
+* This lives here, and only here, because `canonicalStringify` falls back to
+* alphabetical for any key absent from the order: a forgotten entry does not error,
+* it silently relocates. `satisfies` catches a key that is not on `ModelDefinition`;
+* the `keyof` assertion in index.test.ts catches a `ModelDefinition` key missing
+* from this array. Between them, drift fails `tsc`, which runs on every commit.
+*/
+const MODEL_FIELD_ORDER = [
+	"id",
+	"name",
+	"kind",
+	"domain",
+	"i18n",
+	"title_field",
+	"description",
+	"content_path",
+	"locale_strategy",
+	"fields"
+];
 /** Standard name for the dedicated content branch */
@@ -230,2 +253,67 @@ const CONTENTRAIN_BRANCH = "contentrain";
 }
+/**
+* Resolve a field's label for a locale.
+*
+* Falls back in the order a reader would expect: the requested locale, the
+* default locale, any locale present, then the field name. A field with no
+* label resolves to its own name, which is what an editor shows today.
+*/
+function resolveFieldLabel(fieldName, field, locale, defaultLocale) {
+	const { label } = field;
+	if (typeof label === "string") return label;
+	if (label && typeof label === "object") {
+		const byLocale = (locale && label[locale]) ?? (defaultLocale && label[defaultLocale]) ?? Object.values(label)[0];
+		if (byLocale) return byLocale;
+	}
+	return fieldName;
+}
+/**
+* Field names in display order.
+*
+* Exported so every consumer orders identically instead of each reimplementing
+* the fallback. Ascending `order`; fields without one come last, alphabetically
+* among themselves, which is the behaviour a model that has no `order` already
+* has.
+*/
+function orderedFieldNames(fields) {
+	if (!fields) return [];
+	return Object.keys(fields).toSorted((a, b) => {
+		const oa = fields[a]?.order;
+		const ob = fields[b]?.order;
+		if (oa !== void 0 && ob !== void 0 && oa !== ob) return oa - ob;
+		if (oa !== void 0 && ob === void 0) return -1;
+		if (oa === void 0 && ob !== void 0) return 1;
+		return a.localeCompare(b, "en");
+	});
+}
+/**
+* The reserved `title_field` value for dictionary models. A dictionary has no
+* fields — it is a flat key→string map — so there is nothing to point at. Its key
+* *is* the title, and this names that fact rather than leaving the property blank.
+* Only dictionaries may use it; on any other kind `title_field` must name a real field.
+*/
+const DICTIONARY_TITLE_FIELD = "key";
+/**
+* Field types whose value can stand in as a human-readable title.
+*
+* Narrower than "types that hold a string": `color`, `phone`, `icon`, `select`,
+* `date`, `datetime`, `relation` and the media types all store strings, but a row
+* labelled `#ff0000` or `f3a81c09d24e` is exactly the failure this contract exists
+* to prevent.
+*/
+const TITLE_FIELD_TYPES = [
+	"string",
+	"text",
+	"slug",
+	"email",
+	"url",
+	"code",
+	"markdown",
+	"richtext"
+];
+const TITLE_FIELD_TYPE_SET = new Set(TITLE_FIELD_TYPES);
+/** Whether a field of this type may be named as a model's `title_field`. */
+function isTitleFieldType(type) {
+	return TITLE_FIELD_TYPE_SET.has(type);
+}
 /** Extensions we can name a MIME type for. Deliberately small — this is a sniff. */
@@ -512,4 +600,4 @@ const EXTENSION_MIME = {
 //#endregion
-export { CANONICAL_JSON, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, ENTRY_ID_PATTERN, LOCALE_PATTERN, LOCAL_CAPABILITIES, PATH_PATTERNS, SECRET_PATTERNS, SLUG_PATTERN, canonicalStringify, detectSecrets, generateEntryId, isMediaType, parseMarkdownFrontmatter, serializeMarkdownFrontmatter, sortKeys, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
+export { CANONICAL_JSON, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, DICTIONARY_TITLE_FIELD, ENTRY_ID_PATTERN, LOCALE_PATTERN, LOCAL_CAPABILITIES, MODEL_FIELD_ORDER, PATH_PATTERNS, SECRET_PATTERNS, SLUG_PATTERN, TITLE_FIELD_TYPES, canonicalStringify, detectSecrets, generateEntryId, isMediaType, isTitleFieldType, orderedFieldNames, parseMarkdownFrontmatter, resolveFieldLabel, serializeMarkdownFrontmatter, sortKeys, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
 
 //# sourceMappingURL=index.mjs.map

package.json

 {
   "name": "@contentrain/types",
-  "version": "0.9.0",
+  "version": "1.0.2",
   "license": "MIT",
@@ -5,0 +5,0 @@ "description": "Shared TypeScript types for Contentrain ecosystem",

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Improved metrics

Total package byte prevSize

139054

16.12%

Lines of code

600

17.19%

Number of low quality alerts

0

-100%

No dependency changes