@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,344 @@
+"use strict";
+// Implements the Open Knowledge Format (OKF) layout (`bundle/<id>.md`).
+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.OkfLayout = exports.BUNDLE_DIR = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const dataplex = __importStar(require("../gcp/dataplex"));
+const concept_1 = require("../okf/concept");
+const concept_to_entry_1 = require("../okf/concept_to_entry");
+const links_1 = require("../okf/links");
+exports.BUNDLE_DIR = 'bundle';
+const FALLBACK_CONTAINER = 'projects/_/locations/_/entryGroups/_';
+function mapping(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function conceptFiles(dir) {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap((e) => {
+        const p = path.join(dir, e.name);
+        if (e.isDirectory())
+            return conceptFiles(p);
+        return e.name.endsWith('.md') ? [p] : [];
+    });
+}
+function toPosixId(root, file) {
+    return path.relative(root, file).split(path.sep).join('/').replace(/\.md$/, '');
+}
+/**
+ * Resolves the catalog entry ID a concept file maps to, or `undefined` when the
+ * file should be skipped (`<group>_entry`, append-only `log.md`, or a generated
+ * `index.md` shadowed by an explicit `agents.md` / `<dir>.md`).
+ */
+function resolvedEntryName(id, frontmatter, bundlePath) {
+    const residue = mapping(frontmatter[concept_1.RESIDUE_KEY]);
+    const extra = mapping(frontmatter[concept_1.EXTRA_KEY]);
+    if (text(residue['entryType'])?.endsWith('/entrygroup') ||
+        text(extra['type'])?.endsWith('/entrygroup')) {
+        return undefined;
+    }
+    const hasExplicitMeta = frontmatter[concept_1.RESIDUE_KEY] !== undefined ||
+        frontmatter[concept_1.EXTRA_KEY] !== undefined ||
+        frontmatter['type'] !== undefined;
+    // Skip append-only operation logs (`log.md`) that carry no concept frontmatter.
+    if (id === 'log' && !hasExplicitMeta) {
+        return undefined;
+    }
+    // When `agents.md` or `<dir>.md` already exists alongside a directory-listing
+    // `index.md` that has no explicit concept metadata, prefer the explicit file.
+    if (id === 'index' &&
+        !hasExplicitMeta &&
+        fs.existsSync(path.join(bundlePath, 'agents.md'))) {
+        return undefined;
+    }
+    if (id.endsWith('/index') &&
+        !hasExplicitMeta &&
+        fs.existsSync(path.join(bundlePath, `${id.slice(0, -'/index'.length)}.md`))) {
+        return undefined;
+    }
+    const explicitId = text(residue['entryId']) ?? text(extra['entry_id']);
+    if (explicitId)
+        return explicitId;
+    const hasExplicitType = text(residue['entryType']) !== undefined ||
+        text(extra['type']) !== undefined;
+    if (!hasExplicitType) {
+        if (id === 'index')
+            return 'agents';
+        if (id.endsWith('/index'))
+            return id.slice(0, -'/index'.length);
+    }
+    return id;
+}
+function toLocalFromService(entry, localName) {
+    const aspects = {};
+    if (entry.aspects) {
+        for (const [key, val] of Object.entries(entry.aspects)) {
+            aspects[key] = val.data ?? {};
+        }
+    }
+    const src = entry.entrySource ?? {};
+    const resource = {};
+    if (src.resource !== undefined)
+        resource.name = src.resource;
+    if (src.system !== undefined)
+        resource.system = src.system;
+    if (src.platform !== undefined)
+        resource.platform = src.platform;
+    if (src.displayName !== undefined)
+        resource.displayName = src.displayName;
+    if (src.description !== undefined)
+        resource.description = src.description;
+    if (src.labels !== undefined)
+        resource.labels = src.labels;
+    if (src.location !== undefined)
+        resource.location = src.location;
+    if (src.ancestors !== undefined)
+        resource.ancestors = src.ancestors;
+    if (src.createTime !== undefined)
+        resource.createTime = src.createTime;
+    if (src.updateTime !== undefined)
+        resource.updateTime = src.updateTime;
+    if (entry.parentEntry) {
+        const at = entry.parentEntry.indexOf('/entries/');
+        resource.parent =
+            at !== -1
+                ? entry.parentEntry.slice(at + '/entries/'.length)
+                : entry.parentEntry;
+    }
+    return {
+        name: localName,
+        type: dataplex._nameToTypeRef(entry.entryType),
+        resource,
+        aspects: Object.keys(aspects).length ? aspects : undefined,
+    };
+}
+function toServiceFromLocal(entry, container) {
+    const entryType = entry.type.includes('/')
+        ? entry.type
+        : dataplex._typeRefToName(entry.type, 'entry');
+    const res = entry.resource ?? {};
+    let parentEntry;
+    if (res.parent) {
+        parentEntry = res.parent.startsWith('projects/')
+            ? res.parent
+            : `${container}/entries/${res.parent}`;
+    }
+    const source = {};
+    if (res.name !== undefined)
+        source.resource = res.name;
+    if (res.system !== undefined)
+        source.system = res.system;
+    if (res.platform !== undefined)
+        source.platform = res.platform;
+    if (res.displayName !== undefined)
+        source.displayName = res.displayName;
+    if (res.description !== undefined)
+        source.description = res.description;
+    if (res.labels !== undefined)
+        source.labels = res.labels;
+    if (res.location !== undefined)
+        source.location = res.location;
+    if (res.ancestors !== undefined)
+        source.ancestors = res.ancestors;
+    if (res.createTime !== undefined)
+        source.createTime = res.createTime;
+    if (res.updateTime !== undefined)
+        source.updateTime = res.updateTime;
+    const aspects = {};
+    for (const [key, data] of Object.entries(entry.aspects ?? {})) {
+        aspects[key] = { data };
+    }
+    const out = {
+        name: `${container}/entries/${entry.name}`,
+        entryType,
+    };
+    if (parentEntry)
+        out.parentEntry = parentEntry;
+    if (Object.keys(source).length)
+        out.entrySource = source;
+    if (Object.keys(aspects).length)
+        out.aspects = aspects;
+    return out;
+}
+class OkfLayout {
+    _bundlePath;
+    _container;
+    _index = new Map();
+    constructor(bundlePath, entryGroupContainer) {
+        this._bundlePath = bundlePath;
+        this._container =
+            entryGroupContainer && entryGroupContainer.startsWith('projects/')
+                ? entryGroupContainer
+                : FALLBACK_CONTAINER;
+    }
+    get bundlePath() {
+        return this._bundlePath;
+    }
+    bundleExists() {
+        return fs.existsSync(this._bundlePath);
+    }
+    /** Resolves `<bundle>/<id>.md`, rejecting any ID that escapes `bundle/`. */
+    resolveConceptPath(id) {
+        if (!id ||
+            id.includes('\0') ||
+            path.posix.isAbsolute(id) ||
+            path.win32.isAbsolute(id)) {
+            throw new Error(`entry id '${id}' escapes ${exports.BUNDLE_DIR}/`);
+        }
+        const root = path.resolve(this._bundlePath);
+        const file = path.resolve(root, `${id}.md`);
+        if (!file.startsWith(root + path.sep)) {
+            throw new Error(`entry id '${id}' escapes ${exports.BUNDLE_DIR}/`);
+        }
+        return file;
+    }
+    /** Display path relative to workspace root (e.g. `bundle/tables/trips.md`). */
+    relativeBundlePath(name) {
+        const existing = this._index.get(name);
+        if (existing) {
+            const rel = path
+                .relative(this._bundlePath, existing)
+                .split(path.sep)
+                .join('/');
+            return `${exports.BUNDLE_DIR}/${rel}`;
+        }
+        return `${exports.BUNDLE_DIR}/${name}.md`;
+    }
+    async init() {
+        this._index.clear();
+        if (!fs.existsSync(this._bundlePath))
+            return;
+        for (const file of conceptFiles(this._bundlePath)) {
+            const id = toPosixId(this._bundlePath, file);
+            let entryName = id;
+            try {
+                const concept = (0, concept_1.fileContentToConcept)(fs.readFileSync(file, 'utf8'), id);
+                entryName = resolvedEntryName(id, concept.frontmatter, this._bundlePath);
+            }
+            catch {
+                // Defer frontmatter parse errors to loadEntry so pull --force-remove
+                // can still overwrite or prune a corrupted local concept file.
+            }
+            if (!entryName)
+                continue;
+            this._index.set(entryName, file);
+        }
+    }
+    entryExists(name) {
+        const p = this._index.get(name);
+        return !!p && fs.existsSync(p);
+    }
+    listEntries() {
+        return [...this._index.keys()].sort((a, b) => {
+            const depthDiff = a.split('/').length - b.split('/').length;
+            return depthDiff !== 0 ? depthDiff : a.localeCompare(b);
+        });
+    }
+    async loadEntry(name) {
+        const file = this._index.get(name);
+        if (!file || !fs.existsSync(file)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        const id = toPosixId(this._bundlePath, file);
+        const textContent = await fs.promises.readFile(file, 'utf8');
+        const concept = (0, concept_1.fileContentToConcept)(textContent, id);
+        const gcpEntry = (0, concept_to_entry_1.conceptToEntry)(concept, this._container);
+        return toLocalFromService(gcpEntry, name);
+    }
+    /** Validates and builds the `Concept` `saveEntry` would write, without I/O. */
+    previewConcept(name, entry) {
+        this.resolveConceptPath(name);
+        const gcpEntry = toServiceFromLocal({ ...entry, name }, this._container);
+        return (0, concept_to_entry_1.entryToConcept)(gcpEntry, name);
+    }
+    async saveEntry(name, entry) {
+        const file = this.resolveConceptPath(name);
+        const concept = this.previewConcept(name, entry);
+        await fs.promises.mkdir(path.dirname(file), { recursive: true });
+        await fs.promises.writeFile(file, (0, concept_1.conceptToFileContent)(concept), 'utf8');
+        this._index.set(name, file);
+    }
+    async deleteEntry(name) {
+        const indexed = this._index.get(name);
+        const root = path.resolve(this._bundlePath);
+        const file = indexed ? path.resolve(indexed) : this.resolveConceptPath(name);
+        if (!file.startsWith(root + path.sep) || !fs.existsSync(file)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        await fs.promises.unlink(file);
+        this._index.delete(name);
+        this._pruneEmptyDirs(path.dirname(file), root);
+    }
+    /** Reads `bundle/_links.yaml` plus any frontmatter `links` on indexed concepts. */
+    readLinks() {
+        const concepts = [];
+        for (const name of this.listEntries()) {
+            const file = this._index.get(name);
+            if (!file || !fs.existsSync(file))
+                continue;
+            concepts.push((0, concept_1.fileContentToConcept)(fs.readFileSync(file, 'utf8'), name));
+        }
+        return (0, links_1.readBundleLinks)(this._bundlePath, this._container, concepts);
+    }
+    /** Writes or removes `bundle/_links.yaml` to match pulled EntryLinks. */
+    async writeLinks(links) {
+        const linksPath = path.join(this._bundlePath, links_1.LINKS_FILE);
+        if (links.length > 0) {
+            await fs.promises.mkdir(this._bundlePath, { recursive: true });
+            await fs.promises.writeFile(linksPath, (0, links_1.formatLinksYaml)(links, this._container), 'utf8');
+        }
+        else if (fs.existsSync(linksPath)) {
+            await fs.promises.unlink(linksPath);
+        }
+    }
+    _pruneEmptyDirs(dir, stopAt) {
+        let cur = path.resolve(dir);
+        while (cur.startsWith(stopAt + path.sep) && cur !== stopAt) {
+            if (!fs.existsSync(cur) || fs.readdirSync(cur).length > 0)
+                break;
+            fs.rmdirSync(cur);
+            cur = path.dirname(cur);
+        }
+    }
+}
+exports.OkfLayout = OkfLayout;

package/build/ts/kcmd/layouts/semantic-model.d.ts

@@ -0,0 +1,61 @@
+import { CatalogLayout } from '../layout';
+import * as md from '../metadata';
+export declare function profileFilesBeside(dir: string, model: string): {
+    name: string;
+    path: string;
+}[];
+export interface OverviewSidecar {
+    content?: string;
+    contentType?: string;
+    links?: Array<{
+        url: string;
+        title?: string;
+    }>;
+}
+export declare class SemanticModelLayout implements CatalogLayout {
+    private readonly _catalogPath;
+    private readonly _entryGroup?;
+    private readonly _index;
+    constructor(catalogPath: string, entryGroup?: string);
+    init(): Promise<void>;
+    entryExists(_name: string): boolean;
+    listEntries(): string[];
+    modelDocuments(): {
+        name: string;
+        text: string;
+    }[];
+    localProfileFiles(model: string): {
+        path: string;
+        profileName?: string;
+    }[];
+    overviewSidecars(): Map<string, OverviewSidecar>;
+    overviewSidecarPaths(): {
+        entryId: string;
+        path: string;
+    }[];
+    profileDocuments(model: string): {
+        name: string;
+        text: string;
+        path: string;
+    }[];
+    profileDocument(model: string, profileName: string): string | undefined;
+    profilePath(model: string, profileName: string): string;
+    writeProfileDocument(model: string, profileName: string, text: string): void;
+    removeProfileDocument(model: string, profileName: string): void;
+    orphanProfilePaths(): string[];
+    legacyProfileDirs(): string[];
+    private _groupDir;
+    private _siblingProfilePaths;
+    private _legacyProfilePaths;
+    private _modelHeader;
+    hasModel(name: string): boolean;
+    modelPath(name: string): string;
+    writeModelDocument(name: string, text: string): void;
+    removeModelDocument(name: string): void;
+    loadEntry(_name: string): Promise<md.Entry>;
+    saveEntry(_name: string, _entry: md.Entry): Promise<void>;
+    deleteEntry(_name: string): Promise<void>;
+}
+export declare function fileNameOf(layout: SemanticModelLayout, model: string, localPath: string): string;
+export declare function parseOverviewSidecar(text: string, file: string): OverviewSidecar;
+export declare function formatOverviewSidecar({ content, ...rest }: OverviewSidecar): string;