@google-cloud/kcmd 0.0.0-stage → 0.1.0

package/build/ts/kcmd/manifest.d.ts

@@ -0,0 +1,34 @@
+import * as gcp from './gcp';
+import { CatalogSource, Sources } from './source';
+export declare const WORKSPACE_LAYOUTS: readonly ["okf"];
+export type WorkspaceLayout = (typeof WORKSPACE_LAYOUTS)[number];
+export interface SnapshotConfig {
+    entries?: string[];
+    aspects?: string[];
+}
+export interface PublishingConfig {
+    entries?: string[];
+    aspects?: string[];
+}
+export interface Scope {
+    type: string;
+    name: string;
+}
+export declare function layoutOf(manifest: any): WorkspaceLayout | undefined;
+export declare function readWorkspaceLayout(path: string): WorkspaceLayout | undefined;
+export declare function writeWorkspaceLayout(path: string, layout: WorkspaceLayout): void;
+export declare class CatalogManifest {
+    readonly source: CatalogSource;
+    readonly snapshotConfig?: SnapshotConfig;
+    readonly publishingConfig?: PublishingConfig;
+    readonly layout?: WorkspaceLayout;
+    private constructor();
+    private static forNewSource;
+    static forPendingEntryGroup(type: Sources.ENTRYGROUP | Sources.KB, name: string, layout?: WorkspaceLayout): CatalogManifest;
+    static initWithEntryGroup(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithBigQuery(dataset: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithKnowledgeBase(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithSemanticModel(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static load(path: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    save(path: string): void;
+}

package/build/ts/kcmd/manifest.js

@@ -0,0 +1,262 @@
+"use strict";
+// Implements support for creating and loading catalog manifests.
+//
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogManifest = exports.WORKSPACE_LAYOUTS = void 0;
+exports.layoutOf = layoutOf;
+exports.readWorkspaceLayout = readWorkspaceLayout;
+exports.writeWorkspaceLayout = writeWorkspaceLayout;
+const fs = __importStar(require("node:fs"));
+const yaml = __importStar(require("yaml"));
+const z = __importStar(require("zod"));
+const dataplex = __importStar(require("./gcp/dataplex"));
+const source_1 = require("./source");
+const entrygroup_1 = require("./sources/entrygroup");
+const kb_1 = require("./sources/kb");
+// How a workspace stores its entries on disk, when it is not the layout its
+// scope implies (see CatalogSource.layout). `kcmd init --format <layout>`
+// records it, and `pull` and `push` read it back, so the choice is made once
+// per workspace. Only `okf` exists: the entries as an OKF bundle under
+// `bundle/`. A later layout, such as a split workspace that also keeps a
+// semantic model under `catalog/`, is a new value here.
+exports.WORKSPACE_LAYOUTS = ['okf'];
+// The scope types a workspace layout may be recorded for.
+const LAYOUT_SCOPES = [source_1.Sources.ENTRYGROUP, source_1.Sources.KB];
+const manifestSchema = z.object({
+    scope: z.union([z.string(), z.array(z.string())]),
+    // The workspace layout, when it is not the scope's own (see above).
+    layout: z.string().optional(),
+    snapshot: z.object({
+        entries: z.array(z.string()).optional(),
+        aspects: z.array(z.string()).optional()
+    }).optional(),
+    publishing: z.object({
+        entries: z.array(z.string()).optional(),
+        aspects: z.array(z.string()).optional()
+    }).optional(),
+});
+// The workspace layout a parsed catalog.yaml records, or undefined when it
+// records none. Throws naming the problem when the layout is not one kcmd
+// supports, or when the scope's type does not take a layout.
+function layoutOf(manifest) {
+    const layout = manifest?.layout;
+    if (layout === undefined || layout === null)
+        return undefined;
+    if (!exports.WORKSPACE_LAYOUTS.includes(layout)) {
+        throw new Error(`Manifest error: layout '${layout}' is not supported; the supported ` +
+            `layouts are ${exports.WORKSPACE_LAYOUTS.map(l => `'${l}'`).join(', ')}.`);
+    }
+    const scope = manifest?.scope;
+    const type = typeof scope === 'string' ? scope.split('.')[0] : undefined;
+    if (type === undefined || !LAYOUT_SCOPES.includes(type)) {
+        throw new Error(`Manifest error: layout '${layout}' applies only to ` +
+            `${LAYOUT_SCOPES.map(s => `'${s}'`).join(' and ')} scopes.`);
+    }
+    return layout;
+}
+// The workspace layout the catalog.yaml at `path` records, read without
+// resolving the scope, so that a command can choose its path before any call
+// to Knowledge Catalog (the entry group may not exist yet). Undefined when
+// there is no catalog.yaml or it records no layout.
+function readWorkspaceLayout(path) {
+    if (!fs.existsSync(path))
+        return undefined;
+    return layoutOf(yaml.parse(fs.readFileSync(path, 'utf8')));
+}
+// Records `layout` in the catalog.yaml at `path`, keeping every other key and
+// comment as written.
+function writeWorkspaceLayout(path, layout) {
+    const doc = yaml.parseDocument(fs.readFileSync(path, 'utf8'));
+    doc.set('layout', layout);
+    fs.writeFileSync(path, doc.toString(), 'utf8');
+}
+class OfflineEntryGroupSource extends entrygroup_1.EntryGroupSource {
+    async *entries(_ctx) { }
+}
+class OfflineKnowledgeBaseSource extends kb_1.KnowledgeBaseSource {
+    async *entries(_ctx) { }
+}
+class CatalogManifest {
+    source;
+    snapshotConfig;
+    publishingConfig;
+    // The workspace layout, when it is not the scope's own (see the schema).
+    layout;
+    constructor(source, snapshotConfig, publishingConfig, layout) {
+        this.source = source;
+        this.snapshotConfig = snapshotConfig;
+        this.publishingConfig = publishingConfig;
+        this.layout = layout;
+    }
+    // A manifest for a scope `kcmd init` just named, listing the scope's default
+    // aspects under snapshot.aspects.
+    static forNewSource(source) {
+        const aspects = [...source.defaultAspects];
+        return new CatalogManifest(source, aspects.length ? { aspects } : undefined);
+    }
+    // Constructs a manifest for an EntryGroup or KB that has not been created in
+    // Knowledge Catalog yet (used by `kcmd init --format okf` and `kcmd push --dry-run`).
+    static forPendingEntryGroup(type, name, layout) {
+        const [project, location, entryGroup] = name.split('.');
+        if (!project || !location || !entryGroup || name.split('.').length !== 3) {
+            throw new Error('EntryGroup must be in format <projectId>.<locationId>.<entryGroupId>');
+        }
+        const eg = {
+            name: dataplex.catalogContainer(project, location, entryGroup),
+        };
+        const source = type === source_1.Sources.KB
+            ? new OfflineKnowledgeBaseSource(type, name, eg)
+            : new OfflineEntryGroupSource(type, name, eg);
+        const aspects = [...source.defaultAspects];
+        return new CatalogManifest(source, aspects.length ? { aspects } : undefined, undefined, layout);
+    }
+    static async initWithEntryGroup(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.ENTRYGROUP, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithBigQuery(dataset, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.BIGQUERY_DATASET, dataset, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithKnowledgeBase(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.KB, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithSemanticModel(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.SEMANTIC_MODEL, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async load(path, ctx) {
+        const content = fs.readFileSync(path, 'utf8');
+        const parsed = yaml.parse(content);
+        const result = manifestSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new Error(`Manifest error: ${result.error.message}`);
+        }
+        const scope = result.data.scope;
+        const layout = layoutOf(result.data);
+        let source;
+        if (Array.isArray(scope)) {
+            if (scope.length === 0) {
+                throw new Error('Manifest error: scope array cannot be empty.');
+            }
+            const datasets = [];
+            for (const s of scope) {
+                const dotIndex = s.indexOf('.');
+                if (dotIndex === -1) {
+                    throw new Error(`Manifest error: scope '${s}' is invalid.`);
+                }
+                const type = s.substring(0, dotIndex);
+                const name = s.substring(dotIndex + 1);
+                if (type !== source_1.Sources.BIGQUERY_DATASET) {
+                    throw new Error(`Manifest error: Unsupported scope type in multiple scopes: '${type}'.`);
+                }
+                datasets.push(name);
+            }
+            source = await (0, source_1.createSource)(source_1.Sources.BIGQUERY_DATASET, datasets.join(','), ctx);
+        }
+        else {
+            const dotIndex = scope.indexOf('.');
+            if (dotIndex === -1) {
+                throw new Error(`Manifest error: scope '${scope}' is invalid.`);
+            }
+            source = await (0, source_1.createSource)(scope.substring(0, dotIndex), scope.substring(dotIndex + 1), ctx);
+        }
+        const snapshot = result.data.snapshot;
+        if (snapshot) {
+            if (snapshot.entries) {
+                for (const entryType of snapshot.entries) {
+                    const parts = entryType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Entry Type '${entryType}'`);
+                    }
+                }
+            }
+            if (snapshot.aspects) {
+                for (const aspectType of snapshot.aspects) {
+                    const parts = aspectType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Aspect Type '${aspectType}'`);
+                    }
+                }
+            }
+        }
+        const publishing = result.data.publishing;
+        if (publishing) {
+            if (publishing.entries) {
+                for (const entryType of publishing.entries) {
+                    const parts = entryType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Entry Type '${entryType}'`);
+                    }
+                    if (!snapshot?.entries?.includes(entryType)) {
+                        throw new Error(`Manifest error: Publishing entry type '${entryType}' is not listed in snapshot entries.`);
+                    }
+                }
+            }
+            if (publishing.aspects) {
+                for (const aspectType of publishing.aspects) {
+                    const parts = aspectType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Aspect Type '${aspectType}'`);
+                    }
+                    if (!snapshot?.aspects?.includes(aspectType)) {
+                        throw new Error(`Manifest error: Publishing aspect type '${aspectType}' is not listed in snapshot aspects.`);
+                    }
+                }
+            }
+        }
+        return new CatalogManifest(source, snapshot, publishing, layout);
+    }
+    save(path) {
+        let scope;
+        const names = this.source.name.split(',');
+        if (names.length > 1) {
+            scope = names.map(n => `${this.source.type}.${n}`);
+        }
+        else {
+            scope = `${this.source.type}.${this.source.name}`;
+        }
+        const data = {
+            scope: scope,
+            layout: this.layout ?? undefined,
+            snapshot: this.snapshotConfig ?? undefined,
+            publishing: this.publishingConfig ?? undefined
+        };
+        fs.writeFileSync(path, yaml.stringify(data), 'utf8');
+    }
+}
+exports.CatalogManifest = CatalogManifest;

package/build/ts/kcmd/metadata.d.ts

@@ -0,0 +1,25 @@
+export declare const OVERVIEW_ASPECT = "dataplex-types.global.overview";
+export interface Aspect {
+    [key: string]: any;
+}
+export interface Entry {
+    name: string;
+    type: string;
+    resource: {
+        name?: string;
+        system?: string;
+        platform?: string;
+        displayName?: string;
+        description?: string;
+        labels?: Record<string, string>;
+        location?: string;
+        parent?: string;
+        ancestors?: {
+            name: string;
+            type: string;
+        }[];
+        createTime?: string;
+        updateTime?: string;
+    };
+    aspects?: Record<string, Aspect>;
+}

package/build/ts/kcmd/metadata.js

@@ -0,0 +1,8 @@
+"use strict";
+// Defines metadata objects provided by the catalog snapshot
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERVIEW_ASPECT = void 0;
+// The aspect that holds an entry's overview text, which the documents layout
+// writes as a document's body.
+exports.OVERVIEW_ASPECT = 'dataplex-types.global.overview';

package/build/ts/kcmd/okf/catalog_residue.d.ts

@@ -0,0 +1,14 @@
+import * as dataplex from '../gcp/dataplex';
+export declare const RESIDUE_VERSION = 1;
+export declare const OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview";
+export declare const DOCUMENT_ASPECT_KEY = "dataplex-types.global.document";
+export declare const QUERY_TEMPLATE_ASPECT_KEY = "dataplex-types.global.query-template";
+export declare const DEFAULT_DOCUMENT_ENTRY_TYPE = "projects/dataplex-types/locations/global/entryTypes/document";
+export declare const QUERY_TEMPLATE_ENTRY_TYPE = "projects/dataplex-types/locations/global/entryTypes/query-template";
+export declare class ResidueError extends Error {
+}
+/** The aspect whose `type` field becomes the concept's OKF `type`. */
+export declare function typeFacetKey(entryType?: string): string | undefined;
+/** Collects what OKF cannot express. Undefined when there is nothing. */
+export declare function buildResidue(entry: dataplex.Entry, overviewAspectKey: string, body?: string): Record<string, unknown> | undefined;
+export declare function assertResidueOnly(frontmatter: Record<string, unknown>): void;

package/build/ts/kcmd/okf/catalog_residue.js

@@ -0,0 +1,124 @@
+"use strict";
+// Catalog fields OKF has no key for stored in the `x-kcmd` frontmatter block
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResidueError = exports.QUERY_TEMPLATE_ENTRY_TYPE = exports.DEFAULT_DOCUMENT_ENTRY_TYPE = exports.QUERY_TEMPLATE_ASPECT_KEY = exports.DOCUMENT_ASPECT_KEY = exports.OVERVIEW_ASPECT_KEY = exports.RESIDUE_VERSION = void 0;
+exports.typeFacetKey = typeFacetKey;
+exports.buildResidue = buildResidue;
+exports.assertResidueOnly = assertResidueOnly;
+const concept_1 = require("./concept");
+exports.RESIDUE_VERSION = 1;
+exports.OVERVIEW_ASPECT_KEY = 'dataplex-types.global.overview';
+exports.DOCUMENT_ASPECT_KEY = 'dataplex-types.global.document';
+exports.QUERY_TEMPLATE_ASPECT_KEY = 'dataplex-types.global.query-template';
+exports.DEFAULT_DOCUMENT_ENTRY_TYPE = 'projects/dataplex-types/locations/global/entryTypes/document';
+exports.QUERY_TEMPLATE_ENTRY_TYPE = 'projects/dataplex-types/locations/global/entryTypes/query-template';
+class ResidueError extends Error {
+}
+exports.ResidueError = ResidueError;
+const NATIVE_PATHS = [
+    ['entrySource.displayName', 'title'],
+    ['entrySource.description', 'description'],
+    ['entrySource.resource', 'resource'],
+];
+/** The aspect whose `type` field becomes the concept's OKF `type`. */
+function typeFacetKey(entryType) {
+    const short = entryType?.split('/').pop();
+    return short ? `dataplex-types.global.${short}` : undefined;
+}
+function liftedType(data) {
+    return typeof data?.['type'] === 'string' && data['type'] !== '';
+}
+/** Collects what OKF cannot express. Undefined when there is nothing. */
+function buildResidue(entry, overviewAspectKey, body) {
+    const residue = {};
+    if (entry.entryType)
+        residue['entryType'] = entry.entryType;
+    if (entry.parentEntry)
+        residue['parentEntry'] = entry.parentEntry;
+    const source = entry.entrySource ?? {};
+    const carried = {};
+    if (source.system)
+        carried['system'] = source.system;
+    if (source.platform)
+        carried['platform'] = source.platform;
+    if (source.location)
+        carried['location'] = source.location;
+    if (source.ancestors?.length)
+        carried['ancestors'] = source.ancestors;
+    if (source.labels && Object.keys(source.labels).length) {
+        carried['labels'] = source.labels;
+    }
+    if (Object.keys(carried).length)
+        residue['entrySource'] = carried;
+    // An OKF file always ends in a newline, so a body that does not must say so.
+    // This is the body as written to disk, after any trailing section is split
+    // off, since that is what push has to reconstruct.
+    const content = body ?? entry.aspects?.[overviewAspectKey]?.data?.['content'];
+    if (typeof content === 'string' && content && !content.endsWith('\n')) {
+        residue['trailingNewline'] = false;
+    }
+    const facetKey = typeFacetKey(entry.entryType);
+    const aspects = {};
+    for (const [key, aspect] of Object.entries(entry.aspects ?? {})) {
+        if (key === overviewAspectKey)
+            continue;
+        if (key === facetKey && liftedType(aspect.data)) {
+            const { type, ...rest } = aspect.data;
+            aspects[key] = rest;
+            continue;
+        }
+        aspects[key] = aspect.data;
+    }
+    if (Object.keys(aspects).length)
+        residue['aspects'] = aspects;
+    if (!Object.keys(residue).length)
+        return undefined;
+    return { v: exports.RESIDUE_VERSION, ...residue };
+}
+function at(obj, dotted) {
+    let cur = obj;
+    for (const part of dotted.split('.')) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function assertResidueOnly(frontmatter) {
+    const rawExtra = frontmatter[concept_1.EXTRA_KEY];
+    if (rawExtra !== undefined &&
+        rawExtra !== null &&
+        (typeof rawExtra !== 'object' || Array.isArray(rawExtra))) {
+        throw new ResidueError(`${concept_1.EXTRA_KEY} must be a mapping`);
+    }
+    const raw = frontmatter[concept_1.RESIDUE_KEY];
+    if (raw === undefined || raw === null)
+        return;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ResidueError(`${concept_1.RESIDUE_KEY} must be a mapping`);
+    }
+    const residue = raw;
+    const found = [];
+    for (const key of concept_1.KEY_ORDER) {
+        if (residue[key] !== undefined)
+            found.push(`${concept_1.RESIDUE_KEY}.${key} (${key})`);
+    }
+    for (const [dotted, native] of NATIVE_PATHS) {
+        if (at(residue, dotted) !== undefined) {
+            found.push(`${concept_1.RESIDUE_KEY}.${dotted} (${native})`);
+        }
+    }
+    const entryType = residue['entryType'];
+    const facetKey = typeFacetKey(typeof entryType === 'string' ? entryType : undefined);
+    const facet = facetKey
+        ? at(residue, 'aspects')?.[facetKey]
+        : undefined;
+    if (facet &&
+        typeof facet === 'object' &&
+        facet['type'] !== undefined) {
+        found.push(`${concept_1.RESIDUE_KEY}.aspects.${facetKey}.type (type)`);
+    }
+    if (found.length) {
+        throw new ResidueError(`residue duplicates native keys: ${found.join(', ')}`);
+    }
+}

package/build/ts/kcmd/okf/concept.d.ts

@@ -0,0 +1,14 @@
+/** One concept. The `id` is its path in the bundle, without `.md`. */
+export interface Concept {
+    id: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare const RESIDUE_KEY = "x-kcmd";
+export declare const EXTRA_KEY = "extra";
+export declare const ENTRY_SOURCE_KEYS: readonly ["title", "description", "resource"];
+export declare const OKF_METADATA_KEYS: readonly ["tags", "status", "stale_after", "generated", "verified", "sources", "usage_window"];
+export declare const KEY_ORDER: readonly string[];
+export declare function fileContentToConcept(text: string, id: string): Concept;
+/** Renders a concept back into file content. */
+export declare function conceptToFileContent(concept: Concept): string;

package/build/ts/kcmd/okf/concept.js

@@ -0,0 +1,104 @@
+"use strict";
+// An OKF concept: one markdown file with a YAML frontmatter block
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_ORDER = exports.OKF_METADATA_KEYS = exports.ENTRY_SOURCE_KEYS = exports.EXTRA_KEY = exports.RESIDUE_KEY = void 0;
+exports.fileContentToConcept = fileContentToConcept;
+exports.conceptToFileContent = conceptToFileContent;
+const yaml = __importStar(require("yaml"));
+exports.RESIDUE_KEY = 'x-kcmd';
+exports.EXTRA_KEY = 'extra';
+exports.ENTRY_SOURCE_KEYS = ['title', 'description', 'resource'];
+exports.OKF_METADATA_KEYS = [
+    'tags',
+    'status',
+    'stale_after',
+    'generated',
+    'verified',
+    'sources',
+    'usage_window',
+];
+// Anything not listed keeps its insertion order and follows (SPEC §4.1).
+exports.KEY_ORDER = [
+    'type',
+    ...exports.ENTRY_SOURCE_KEYS,
+    ...exports.OKF_METADATA_KEYS,
+];
+function fileContentToConcept(text, id) {
+    const lines = text.split(/\r?\n/);
+    const end = lines[0] === '---' ? lines.indexOf('---', 1) : -1;
+    if (end === -1) {
+        return { id, frontmatter: {}, body: text };
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(lines.slice(1, end).join('\n'));
+    }
+    catch (e) {
+        throw new Error(`${id}.md: invalid frontmatter: ${e instanceof Error ? e.message : e}`);
+    }
+    const frontmatter = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : {};
+    return { id, frontmatter, body: lines.slice(end + 1).join('\n') };
+}
+/** Renders a concept back into file content. */
+function conceptToFileContent(concept) {
+    const { frontmatter, body } = concept;
+    const ordered = {};
+    for (const key of exports.KEY_ORDER) {
+        if (key in frontmatter && frontmatter[key] !== undefined) {
+            ordered[key] = frontmatter[key];
+        }
+    }
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (key === exports.RESIDUE_KEY ||
+            key === exports.EXTRA_KEY ||
+            key in ordered ||
+            value === undefined) {
+            continue;
+        }
+        ordered[key] = value;
+    }
+    if (frontmatter[exports.EXTRA_KEY] !== undefined) {
+        ordered[exports.EXTRA_KEY] = frontmatter[exports.EXTRA_KEY];
+    }
+    if (frontmatter[exports.RESIDUE_KEY] !== undefined) {
+        ordered[exports.RESIDUE_KEY] = frontmatter[exports.RESIDUE_KEY];
+    }
+    const block = yaml.stringify(ordered).trimEnd();
+    const text = body.endsWith('\n') || body === '' ? body : `${body}\n`;
+    return `---\n${block}\n---\n${text}`;
+}

package/build/ts/kcmd/okf/concept_to_entry.d.ts

@@ -0,0 +1,8 @@
+import * as dataplex from '../gcp/dataplex';
+import { Concept } from './concept';
+export declare class ConceptError extends Error {
+}
+/** Maps OKF human-readable `type` labels to Dataplex `document.type` slugs. */
+export declare function normalizeOkfDocType(rawType: string): string;
+export declare function entryToConcept(entry: dataplex.Entry, id: string): Concept;
+export declare function conceptToEntry(concept: Concept, entryGroup: string): dataplex.Entry;