@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,542 @@
+"use strict";
+// Implements the SemanticModel layout.
+//
+// The whole model definition is a single Apache Ossie document per model,
+// located at `catalog/EntryGroups/<entryGroupId>/<model>.yaml`, with its
+// profile files beside it. Each Knowledge Catalog entry of the model may have
+// an overview sidecar at its entry id under the same directory:
+// `<model>.overview.md` for the model and, for example,
+// `<model>/entities/<entity>.overview.md` for an entity.
+//
+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.SemanticModelLayout = void 0;
+exports.profileFilesBeside = profileFilesBeside;
+exports.fileNameOf = fileNameOf;
+exports.parseOverviewSidecar = parseOverviewSidecar;
+exports.formatOverviewSidecar = formatOverviewSidecar;
+const glob = __importStar(require("glob"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("yaml"));
+const loader_1 = require("../semantic/loader");
+const names_1 = require("../semantic/names");
+const yaml_options_1 = require("../semantic/yaml_options");
+const documents_1 = require("./documents");
+// Sidecar suffixes that are NOT model documents.
+const SIDECAR_SUFFIXES = ['.aspects.yaml', '.overview.yaml'];
+// A binding-profile file sits beside its model as `<model>.profile.<name>.yaml`.
+// `<model>.profile.yaml`, with no name, is not a model either.
+const PROFILE_FILE = /^(.+)\.profile\.([^.]+)\.yaml$/;
+// Any file shaped like a profile file, including a nameless one and one whose
+// profile name has a dot, which is never a model either.
+const ANY_PROFILE_FILE = /\.profile\.(.*\.)?yaml$/;
+// The model and profile a `<model>.profile.<name>.yaml` file name names, or
+// undefined when `fileName` is not one.
+function profileFileName(fileName) {
+    const m = fileName.match(PROFILE_FILE);
+    return m ? { model: m[1], profile: m[2] } : undefined;
+}
+// Each `<model>.profile.<name>.yaml` in `dir`, by profile name.
+function profileFilesBeside(dir, model) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of fs.readdirSync(dir)) {
+        const named = profileFileName(f);
+        if (named?.model === model) {
+            out.push({ name: named.profile, path: path.join(dir, f) });
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+// The suffix of an entry's overview sidecar.
+const OVERVIEW_SIDECAR = '.overview.md';
+// The profile name reserved for the inline bindings in the model file.
+const DEFAULT_PROFILE_NAME = 'default';
+// The flavor that keeps its profiles inline, in a GOOGLE block, and so has no
+// sibling profile files.
+const VANILLA_VERSION = '0.2.0.dev0';
+// The error for a sibling profile file beside a vanilla model, which keeps its
+// profiles in its GOOGLE block.
+function vanillaSiblingError(file, model) {
+    return `Profile file '${file}' sits beside '${model}.yaml', which is a ` +
+        `${VANILLA_VERSION} document; sibling profile files are Google-flavor ` +
+        `only, and a ${VANILLA_VERSION} model keeps its profiles in its GOOGLE ` +
+        `block.`;
+}
+class SemanticModelLayout {
+    _catalogPath;
+    _entryGroup;
+    // Maps a model handle (the document's file basename) to its absolute path.
+    _index = new Map();
+    constructor(catalogPath, entryGroup) {
+        this._catalogPath = catalogPath;
+        this._entryGroup = entryGroup;
+    }
+    async init() {
+        this._index.clear();
+        if (!fs.existsSync(this._catalogPath)) {
+            return;
+        }
+        // A model document is a top-level `<model>.yaml` under the configured
+        // EntryGroup dir, excluding the `.aspects.yaml` / `.overview.yaml`
+        // sidecars. Scoping to the manifest's entryGroup keeps unrelated group
+        // directories out of the deploy set and avoids the basename collision that
+        // a cross-group `EntryGroups/*/*.yaml` glob would produce (same file name
+        // in two groups). Fall back to all groups only when no scope was provided.
+        const pattern = this._entryGroup ?
+            `EntryGroups/${this._entryGroup}/*.yaml` :
+            'EntryGroups/*/*.yaml';
+        const matches = await glob.glob(pattern, {
+            cwd: this._catalogPath,
+            absolute: true,
+            nodir: true,
+        });
+        // glob returns files in directory order, which differs between
+        // filesystems. Sorted, push and `kcmd profiles` visit models in the same
+        // order everywhere.
+        for (const localPath of matches.sort()) {
+            if (SIDECAR_SUFFIXES.some(s => localPath.endsWith(s))) {
+                continue;
+            }
+            const base = path.basename(localPath);
+            if (ANY_PROFILE_FILE.test(base))
+                continue;
+            const name = path.basename(localPath, '.yaml');
+            this._index.set(name, localPath);
+        }
+    }
+    // Consistent with listEntries(): this push-only layout exposes no per-entry
+    // Knowledge Catalog files, so no entry "exists" at the KC layer. Answering
+    // from _index (which holds model-document handles) would report an entry that
+    // listEntries() won't return and that loadEntry()/saveEntry() reject. The
+    // model documents are surfaced via modelDocuments(), not as entries.
+    entryExists(_name) {
+        return false;
+    }
+    // This is a push-only layout: it exposes no per-entry Knowledge Catalog
+    // files, so it lists no entries. Returning model handles here would make
+    // callers that pair listEntries() with loadEntry() -- e.g. the MCP server --
+    // list a model and then throw on read. modelDocuments() is the sole accessor
+    // for the authored model documents.
+    listEntries() {
+        return [];
+    }
+    // Reads the raw Ossie document text for each discovered model. This is the
+    // seam the push path consumes; the Ossie text is parsed to the semantic IR by
+    // the loader, not mapped to a Knowledge Catalog entry here.
+    modelDocuments() {
+        const docs = [];
+        for (const [name, localPath] of this._index) {
+            docs.push({ name, text: fs.readFileSync(localPath, 'utf8') });
+        }
+        return docs;
+    }
+    // Every local profile file of a model, for pull to find the ones the
+    // catalog did not return: each sibling file whose name is a valid profile
+    // name, with that name, then each file in the older `<model>.profiles/`
+    // directory, which push no longer reads. It applies no flavor check. A
+    // sibling file with an invalid profile name is left out; push rejects it,
+    // naming it.
+    localProfileFiles(model) {
+        return [
+            ...this._siblingProfilePaths(model)
+                .filter(p => !(0, names_1.nameProblem)('profile', p.name))
+                .map(p => ({ path: p.path, profileName: p.name })),
+            ...this._legacyProfilePaths(model).map(p => ({ path: p.path })),
+        ];
+    }
+    // The overview sidecar of each entry, by entry id. Throws naming a sidecar
+    // parseOverviewSidecar rejects.
+    overviewSidecars() {
+        return new Map(this.overviewSidecarPaths().map(({ entryId, path: p }) => [
+            entryId,
+            parseOverviewSidecar(fs.readFileSync(p, 'utf8'), path.relative(this._groupDir(), p)),
+        ]));
+    }
+    // Each overview sidecar on disk at a model, entity, metric or relationship
+    // path, with the entry id its path names, in path order.
+    overviewSidecarPaths() {
+        if (!this._entryGroup)
+            return [];
+        const dir = this._groupDir();
+        const files = glob.globSync([
+            `*${OVERVIEW_SIDECAR}`,
+            `*/{entities,metrics,relationships}/*${OVERVIEW_SIDECAR}`,
+        ], { cwd: dir, nodir: true, posix: true });
+        return files.sort().map(f => ({
+            entryId: f.slice(0, -OVERVIEW_SIDECAR.length),
+            path: path.join(dir, f),
+        }));
+    }
+    // The text and path of each profile file beside a model, by profile name.
+    // Sibling files are checked first, and the first problem found with any of
+    // them throws, naming the file:
+    //   - a `<model>.profile.yaml` names no profile;
+    //   - the file's `name:` must equal its filename suffix, because `pull`
+    //     writes a profile back to the file its name implies;
+    //   - `default` names the model's inline bindings, so no profile may use it;
+    //   - a vanilla `0.2.0.dev0` model keeps its profiles in its GOOGLE block, so
+    //     it must have no sibling profile files;
+    //   - the files are named after the model, so the model file must declare
+    //     that name, which `pull` uses to name both.
+    profileDocuments(model) {
+        const nameless = this._entryGroup ?
+            path.join(this._groupDir(), `${model}.profile.yaml`) :
+            undefined;
+        if (nameless && fs.existsSync(nameless)) {
+            throw new Error(`Profile file '${path.basename(nameless)}' names no profile; ` +
+                `rename it '${model}.profile.<name>.yaml'.`);
+        }
+        const prefix = `${model}.profile.`;
+        const badName = this._entryGroup && fs.existsSync(this._groupDir()) ?
+            fs.readdirSync(this._groupDir()).find(f => {
+                if (!f.startsWith(prefix) || !f.endsWith('.yaml'))
+                    return false;
+                const n = f.slice(prefix.length, -'.yaml'.length);
+                return f !== `${model}.profile.yaml` &&
+                    (0, names_1.nameProblem)('profile', n) !== undefined;
+            }) :
+            undefined;
+        if (badName) {
+            throw new Error(`Profile file '${badName}' has profile name '${badName.slice(prefix.length, -'.yaml'.length)}'; a profile ` +
+                `name is a letter followed by letters, digits, underscores and ` +
+                `hyphens.`);
+        }
+        const siblings = this._siblingProfilePaths(model);
+        if (!siblings.length)
+            return [];
+        const modelFile = `${model}.yaml`;
+        const header = this._modelHeader(model);
+        if (header.name !== undefined && header.name !== model) {
+            // A name the loader rejects cannot name the files either.
+            const problem = (0, names_1.nameProblem)('model', header.name);
+            if (problem)
+                throw new Error(`Model file '${modelFile}': ${problem}`);
+            throw new Error(`Profile file '${path.basename(siblings[0].path)}' is named after ` +
+                `'${modelFile}', which declares model '${header.name}'; a profile ` +
+                `file is named after its model, so name the model file and its ` +
+                `profile files after '${header.name}'.`);
+        }
+        const version = header.version;
+        const docs = [];
+        // Profile names are unique ignoring case.
+        const byLowerName = new Map();
+        for (const { name, path: p } of siblings) {
+            const file = path.basename(p);
+            const twin = byLowerName.get(name.toLowerCase());
+            if (twin) {
+                throw new Error(`Profile files '${twin}' and '${file}' name the same profile; ` +
+                    `profile names are unique ignoring case.`);
+            }
+            byLowerName.set(name.toLowerCase(), file);
+            if (!fs.statSync(p).isFile()) {
+                throw new Error(`Profile file '${file}' is not a file.`);
+            }
+            if (version === VANILLA_VERSION) {
+                throw new Error(vanillaSiblingError(file, model));
+            }
+            const text = fs.readFileSync(p, 'utf8');
+            const declared = parseProfileName(text, file, name);
+            const reserved = (n) => n?.toLowerCase() === DEFAULT_PROFILE_NAME;
+            if (reserved(name)) {
+                throw new Error(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
+                    `inline bindings in '${modelFile}'; remove '${file}'.`);
+            }
+            if (reserved(declared)) {
+                throw new Error(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
+                    `inline bindings in '${modelFile}'; change the name in '${file}' to '${name}'.`);
+            }
+            if (declared === undefined) {
+                throw new Error(`Profile file '${file}' declares no name; add 'name: ${name}'.`);
+            }
+            if (declared !== name) {
+                throw new Error(`Profile file '${file}' declares name '${declared}', which ` +
+                    `does not match filename suffix '${name}'.`);
+            }
+            docs.push({ name, text, path: p });
+        }
+        return docs;
+    }
+    // The text of one profile file beside a model, or undefined when the model
+    // has no profile of that name. The rules `profileDocuments` enforces apply.
+    profileDocument(model, profileName) {
+        return this.profileDocuments(model).find(d => d.name === profileName)
+            ?.text;
+    }
+    // The path a profile file for this model and profile name maps to:
+    // `<catalog>/EntryGroups/<entryGroup>/<model>.profile.<name>.yaml`. Throws
+    // when `profileName` breaks the profile naming rule or `model` holds a path
+    // separator, so a name read from elsewhere cannot point outside the entry
+    // group.
+    profilePath(model, profileName) {
+        if (/[\\/]/.test(model)) {
+            throw new Error(`Model name '${model}' is not valid in a file name.`);
+        }
+        if ((0, names_1.nameProblem)('profile', profileName)) {
+            throw new Error(`Profile name '${profileName}' is not valid; a profile name is a ` +
+                `letter, then letters, digits, underscores or hyphens.`);
+        }
+        return path.join(this._groupDir(), `${model}.profile.${profileName}.yaml`);
+    }
+    // Writes a profile file beside its model, creating the EntryGroup directory
+    // if needed, for `pull` to write a catalog profile through.
+    writeProfileDocument(model, profileName, text) {
+        const localPath = this.profilePath(model, profileName);
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        fs.writeFileSync(localPath, text);
+    }
+    // Deletes a profile file, for `pull --force-remove` to drop a local profile
+    // the catalog no longer has.
+    removeProfileDocument(model, profileName) {
+        const localPath = this.profilePath(model, profileName);
+        if (fs.existsSync(localPath))
+            fs.rmSync(localPath);
+    }
+    // Profile files with no model beside them, for push, `kcmd profiles` and
+    // `kcmd skills-generate` to reject: any
+    // `<prefix>.profile.<name>.yaml`, or nameless `<prefix>.profile.yaml`, where
+    // `<prefix>.yaml` does not exist.
+    orphanProfilePaths() {
+        const dir = this._entryGroup ? this._groupDir() : undefined;
+        if (!dir || !fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter(f => {
+            if (f.startsWith('.') || !ANY_PROFILE_FILE.test(f))
+                return false;
+            const prefix = f.slice(0, f.indexOf('.profile.'));
+            return !fs.existsSync(path.join(dir, `${prefix}.yaml`));
+        })
+            .sort()
+            .map(f => path.join(dir, f));
+    }
+    // The older `<model>.profiles/` directories in the EntryGroup dir that still
+    // hold a profile file, which push, `kcmd profiles` and `kcmd skills-generate`
+    // reject.
+    legacyProfileDirs() {
+        const dir = this._entryGroup ? this._groupDir() : undefined;
+        if (!dir || !fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter(f => f.endsWith('.profiles') &&
+            fs.statSync(path.join(dir, f), { throwIfNoEntry: false })
+                ?.isDirectory() &&
+            this._legacyProfilePaths(f.slice(0, -'.profiles'.length))
+                .length > 0)
+            .sort()
+            .map(f => path.join(dir, f));
+    }
+    _groupDir() {
+        if (!this._entryGroup) {
+            throw new Error('SemanticModel layout has no entry group; cannot resolve a profile path.');
+        }
+        return path.join(this._catalogPath, 'EntryGroups', this._entryGroup);
+    }
+    _siblingProfilePaths(model) {
+        return this._entryGroup ? profileFilesBeside(this._groupDir(), model) : [];
+    }
+    // `<model>.profiles/*.yaml`, each named by its file basename, for pull to
+    // find the stale ones (see localProfileFiles). A model name
+    // that pull read from the catalog may hold a path separator, and with it a
+    // `..` segment, so such a name has no directory here.
+    _legacyProfilePaths(model) {
+        if (!this._entryGroup || /[\\/]/.test(model))
+            return [];
+        const dir = path.join(this._groupDir(), `${model}.profiles`);
+        if (!fs.existsSync(dir))
+            return [];
+        const out = [];
+        for (const entry of fs.readdirSync(dir)) {
+            if (!entry.endsWith('.yaml'))
+                continue;
+            if (SIDECAR_SUFFIXES.some(s => entry.endsWith(s)))
+                continue;
+            out.push({ name: path.basename(entry, '.yaml'), path: path.join(dir, entry) });
+        }
+        return out.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    // The `version` and model `name` a model document declares, each undefined
+    // when the document has none. In a document with a YAML error, the version
+    // is read as the lookup of its GOOGLE block profiles reads it, and is
+    // undefined when the error may change it. The name is undefined then, since
+    // the error can change the name the text seems to declare. The loader
+    // reports the error.
+    _modelHeader(model) {
+        const localPath = this._index.get(model);
+        if (!localPath)
+            return {};
+        try {
+            const text = fs.readFileSync(localPath, 'utf8');
+            let doc;
+            try {
+                doc = yaml.parse(text, yaml_options_1.YAML_OPTIONS);
+            }
+            catch {
+                // A YAML error; the name stays undefined.
+            }
+            const name = Array.isArray(doc?.semantic_model) ?
+                doc.semantic_model[0]?.name :
+                undefined;
+            return {
+                version: (0, loader_1.modelDocumentVersion)(text),
+                name: typeof name === 'string' ? name : undefined,
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    // True when a model document with this handle already exists on disk. `pull`
+    // uses it to report which files it would overwrite vs. create.
+    hasModel(name) {
+        return fs.existsSync(this.modelPath(name));
+    }
+    // The absolute path a model document with this handle maps to:
+    // `<catalog>/EntryGroups/<entryGroup>/<name>.yaml`. Path separators in the
+    // model name are replaced so a name still yields a single flat file. Requires
+    // the layout to be scoped to an entry group (the semantic-model source always
+    // is).
+    modelPath(name) {
+        if (!this._entryGroup) {
+            throw new Error('SemanticModel layout has no entry group; cannot resolve a model path.');
+        }
+        const file = `${name.replace(/[/\\]/g, '_')}.yaml`;
+        return path.join(this._catalogPath, 'EntryGroups', this._entryGroup, file);
+    }
+    // Writes a model's serialized document to its path, creating the EntryGroup
+    // directory if needed, and indexes it so a later modelDocuments() sees it.
+    // This is the sink `pull` writes reconstructed models to.
+    writeModelDocument(name, text) {
+        const localPath = this.modelPath(name);
+        fs.mkdirSync(path.dirname(localPath), { recursive: true });
+        fs.writeFileSync(localPath, text);
+        this._index.set(name, localPath);
+    }
+    // Deletes a model document from disk and the index. `pull --force-remove`
+    // uses it to drop a local model the catalog no longer names before writing
+    // the catalog's, so the entry group is never left holding two models.
+    removeModelDocument(name) {
+        const localPath = this.modelPath(name);
+        if (fs.existsSync(localPath)) {
+            fs.rmSync(localPath);
+        }
+        this._index.delete(name);
+    }
+    // The Knowledge Catalog entry-level members are not applicable to this
+    // push-only layout; the model is authored as a single Ossie document, not as
+    // per-entry Knowledge Catalog files. These are wired when KC-resource emit
+    // and semantic-model `pull` land.
+    async loadEntry(_name) {
+        throw new Error('The SemanticModel layout does not expose per-entry Knowledge Catalog files yet.');
+    }
+    async saveEntry(_name, _entry) {
+        throw new Error('The SemanticModel layout does not support writing per-entry files yet.');
+    }
+    async deleteEntry(_name) {
+        throw new Error('The SemanticModel layout does not support deleting per-entry files yet.');
+    }
+}
+exports.SemanticModelLayout = SemanticModelLayout;
+// The name push gives a model file or profile file of the model `model`: its
+// path relative to the entry group directory, with `/` between segments.
+function fileNameOf(layout, model, localPath) {
+    return path.relative(path.dirname(layout.modelPath(model)), localPath)
+        .split(path.sep)
+        .join('/');
+}
+// Reads the overview sidecar `text`. Throws naming `file` when its frontmatter
+// does not parse, holds a key other than contentType and links, gives a
+// contentType other than MARKDOWN or HTML, or a link with no url.
+function parseOverviewSidecar(text, file) {
+    const fail = (problem) => new Error(`Overview sidecar '${file}': ${problem}`);
+    let split;
+    try {
+        split = (0, documents_1.splitFrontmatter)(text);
+    }
+    catch (err) {
+        throw fail(`its frontmatter does not parse: ${err?.message ?? err}`);
+    }
+    const metadata = split.metadata ?? {};
+    const extra = typeof metadata === 'object' && !Array.isArray(metadata) ?
+        Object.keys(metadata).find(k => k !== 'contentType' && k !== 'links') :
+        '';
+    if (extra !== undefined) {
+        throw fail(`its frontmatter holds only contentType and links` +
+            (extra ? `, not '${extra}'.` : '.'));
+    }
+    const { contentType, links } = metadata;
+    if (contentType !== undefined && contentType !== 'MARKDOWN' &&
+        contentType !== 'HTML') {
+        throw fail(`contentType is MARKDOWN or HTML, not '${contentType}'.`);
+    }
+    const isLink = (l) => typeof l?.url === 'string' &&
+        ['string', 'undefined'].includes(typeof l.title) &&
+        Object.keys(l).every(k => k === 'url' || k === 'title');
+    if (links !== undefined && !(Array.isArray(links) && links.every(isLink))) {
+        throw fail('links is a list of entries, each a url and an optional title.');
+    }
+    return { content: split.body.trim() || undefined, contentType, links };
+}
+// The text of the overview sidecar that holds `overview`.
+function formatOverviewSidecar({ content = '', ...rest }) {
+    // The body ends with a newline, which push trims.
+    const body = content && !content.endsWith('\n') ? `${content}\n` : content;
+    // Content whose first line is `---` would otherwise read back as frontmatter.
+    return Object.keys(rest).length || body.split(/\r?\n/, 1)[0] === '---' ?
+        (0, documents_1.joinFrontmatter)(rest, body) :
+        body;
+}
+// The `name` a profile file declares at its top level, or undefined when it
+// declares none. A file that does not parse or that uses the legacy
+// `semantic_model:` wrapper throws, naming the file.
+function parseProfileName(text, file, name) {
+    let doc;
+    try {
+        doc = yaml.parse(text, yaml_options_1.YAML_OPTIONS);
+    }
+    catch (err) {
+        throw new Error(`Profile file '${file}' does not parse: ${err?.message ?? err}`);
+    }
+    if (doc?.semantic_model !== undefined) {
+        throw new Error(`Profile file '${file}' uses the legacy 'semantic_model:' wrapper, ` +
+            `which is no longer supported; write its entities, relationships ` +
+            `and actions at the top level under 'name: ${name}', and move any ` +
+            `'deployment_target' to an entry under 'deployments:' in the model ` +
+            `file with 'profile: ${name}'.`);
+    }
+    return typeof doc?.name === 'string' ? doc.name : undefined;
+}

package/build/ts/kcmd/layouts/standard.d.ts

@@ -0,0 +1,13 @@
+import { CatalogLayout } from '../layout';
+import * as md from '../metadata';
+export declare class StandardLayout implements CatalogLayout {
+    private readonly _catalogPath;
+    private readonly _index;
+    constructor(catalogPath: string);
+    init(): Promise<void>;
+    entryExists(name: string): boolean;
+    listEntries(): string[];
+    loadEntry(name: string): Promise<md.Entry>;
+    saveEntry(name: string, entry: md.Entry): Promise<void>;
+    deleteEntry(name: string): Promise<void>;
+}

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

@@ -0,0 +1,108 @@
+"use strict";
+// Implements the standard layout (yaml files in directory)
+//
+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.StandardLayout = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const glob = __importStar(require("glob"));
+const yaml = __importStar(require("yaml"));
+class StandardLayout {
+    _catalogPath;
+    _index = new Map();
+    constructor(catalogPath) {
+        this._catalogPath = catalogPath;
+    }
+    async init() {
+        this._index.clear();
+        if (!fs.existsSync(this._catalogPath)) {
+            return;
+        }
+        const matches = await glob.glob('**/*.yaml', {
+            cwd: this._catalogPath,
+            absolute: true,
+            nodir: true,
+        });
+        for (const localPath of matches) {
+            try {
+                const content = await fs.promises.readFile(localPath, 'utf8');
+                const metadata = yaml.parse(content);
+                if (metadata && metadata.name) {
+                    this._index.set(metadata.name, localPath);
+                }
+            }
+            catch (err) {
+                // A file that fails to read or parse is left out of the index, so it is
+                // never listed and never pushed. Warn rather than drop it silently:
+                // push otherwise makes the destination match the directory, and a file
+                // vanishing from that set is easy to miss.
+                const reason = err instanceof Error ? err.message : String(err);
+                const relPath = path.relative(this._catalogPath, localPath);
+                console.warn(`Skipping unreadable catalog file '${relPath}': ${reason}`);
+            }
+        }
+    }
+    entryExists(name) {
+        const entryPath = this._index.get(name);
+        return !!entryPath && fs.existsSync(entryPath);
+    }
+    listEntries() {
+        return Array.from(this._index.keys());
+    }
+    async loadEntry(name) {
+        const entryPath = this._index.get(name);
+        if (!entryPath || !fs.existsSync(entryPath)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        const content = await fs.promises.readFile(entryPath, 'utf8');
+        return yaml.parse(content);
+    }
+    async saveEntry(name, entry) {
+        const entryPath = path.join(this._catalogPath, `${name}.yaml`);
+        await fs.promises.mkdir(path.dirname(entryPath), { recursive: true });
+        await fs.promises.writeFile(entryPath, yaml.stringify(entry), 'utf8');
+        this._index.set(name, entryPath);
+    }
+    async deleteEntry(name) {
+        const entryPath = this._index.get(name);
+        if (!entryPath || !fs.existsSync(entryPath)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        await fs.promises.unlink(entryPath);
+        this._index.delete(name);
+    }
+}
+exports.StandardLayout = StandardLayout;