@plainconceptsplatform/workflows 1.10.1 → 1.12.0

package/README.md

@@ -81,7 +81,7 @@ npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci
 
 ## Templates
 
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, and `opencode.ci.json`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-error-report`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, `opencode.ci.json`, `platform-template` and `quality-gates`. CI templates are stack-specific copies, not a combined template. `quality-gates` and `platform-template` are bundles: they stay package-managed and `update` refreshes them where they are installed. `platform-template` reads the platform contract, `.platform/contract.yml`; see `docs/platform-contracts.md` and `docs/family-templates.md` in the repository. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
 
 `agentics-error-report` is worth installing everywhere. Once a day it classifies how *this package's* workflows behaved in the repository and files what broke upstream, so the package gets fixed instead of every repository working around the same bug. It is deterministic no model runs, because a model asked to summarise a failure paraphrases whatever the log held and it sends only the names this package gives its own workflows, jobs and steps, a conclusion, a bucketed runner label, a count and a classification id. No log line, branch, title, path or issue number leaves the repository, the repository's own workflows are counted and never inspected, and a leak scanner withholds any report mentioning the repository or its owner and fails the run rather than filing it. Clear `UPSTREAM_NAME` in its `env:` to compute the report into the job summary and file nothing.
 

package/dist/catalog-installation.js

@@ -10,6 +10,7 @@ import { processRoutes, excludedWorkerFiles } from "./route-processing.js";
 import { generateOpencodeCi, generateOpencodeConfig, generateStackDefaults, injectStackEnv, shippedVerifyDefaults } from "./stack-defaults.js";
 import { mergeRouter, mergeWorker } from "./worker-env.js";
 import { fetchBaseline, hasOwnershipHeader, installedVersion, packageVersion, stampVersion } from "./package-baseline.js";
+import { installBundle, isBundleTemplate } from "./template-bundles.js";
 const execFileAsync = promisify(execFile);
 const sourceMappings = [
     ["actions", ".github/actions"],
@@ -286,6 +287,10 @@ const templateCompanions = {
 };
 export async function installTemplate(repositoryPath, template, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
+    if (isBundleTemplate(template)) {
+        const bundle = await installBundle(repositoryPath, template, sourcePath, { force: options.force });
+        return { installed: bundle.installed, conflicts: [] };
+    }
     const meta = catalogTemplateMeta(template);
     const source = join(sourcePath, "templates", meta.directory, meta.file);
     const target = meta.target;

package/dist/catalog-listing.js

@@ -1,5 +1,7 @@
 import { access, constants } from "node:fs/promises";
 import { join } from "node:path";
+import { catalogSourcePath } from "./catalog-installation.js";
+import { installedBundles } from "./template-bundles.js";
 import { catalogTemplates, workflowRoutes } from "./workflow-catalog.js";
 export async function listCatalog(options = {}) {
     const basePath = options.installedPath ?? process.cwd();
@@ -10,12 +12,15 @@ export async function listCatalog(options = {}) {
         file: route.worker,
         installed: await isFileInstalled(basePath, route.worker),
     })));
+    // A bundle counts as installed by its ownership headers, not by its paths: a repository may keep
+    // its own headerless files at the same places.
+    const bundles = await installedBundles(basePath, catalogSourcePath());
     const templates = await Promise.all(catalogTemplates.map(async (template) => ({
         kind: "template",
         name: template.name,
         description: template.description,
         file: template.file,
-        installed: await isFileInstalled(basePath, template.file, template.target),
+        installed: template.bundle === true ? bundles.includes(template.name) : await isFileInstalled(basePath, template.file, template.target),
     })));
     return [...routes, ...templates];
 }

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
-import { installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { catalogSourcePath, installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
+import { installBundle, installedBundles, isBundleTemplate } from "./template-bundles.js";
 import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
 import { packageVersion } from "./package-baseline.js";
 import { routeNames, templateNames } from "./workflow-catalog.js";
@@ -48,7 +49,9 @@ What an update does to a package-managed file:
   follows the package when its default changes. The agent runner pool and the engine gateway URL
   are kept as well. Everything else in the file is the package's.
   A file whose ownership header was removed is yours and is left alone unless --force is passed.
-  Templates are yours after installation and are replaced only with --force.
+  Single-file templates are yours after installation and are replaced only with --force.
+  Bundle templates (quality-gates, platform-template) stay package-managed like the catalog:
+  add --template installs one, and update refreshes it only where its files carry the header.
 
 Options:
   --dry-run                                   Print what add or update would change, write nothing.
@@ -118,15 +121,25 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         const allInstalled = [];
         let catalog;
         const templatesPlanned = [];
+        const bundles = [];
+        const sourcePath = catalogSourcePath();
         // The installed set is always part of the target set: adding a route never drops another,
-        // and a plain update refreshes exactly what is there.
+        // and a plain update refreshes exactly what is there, bundle templates included. A bundle
+        // nobody installed is never added by an update.
         if (routes.length > 0 || template === undefined) {
             const selectedRoutes = unionRoutes(routes, await installedRoutes(repositoryPath));
             catalog = await installCatalog(repositoryPath, { force, dryRun, selectedRoutes, inspection, baseline });
             allConflicts.push(...catalog.conflicts);
             allInstalled.push(...catalog.installed);
+            for (const name of await installedBundles(repositoryPath, sourcePath)) {
+                if (name !== template)
+                    bundles.push(await installBundle(repositoryPath, name, sourcePath, { force, dryRun }));
+            }
+        }
+        if (template !== undefined && isBundleTemplate(template)) {
+            bundles.push(await installBundle(repositoryPath, template, sourcePath, { force, dryRun }));
         }
-        if (template !== undefined) {
+        else if (template !== undefined) {
             if (dryRun) {
                 templatesPlanned.push(template);
             }
@@ -142,11 +155,14 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         }
         for (const warning of catalog?.warnings ?? [])
             console.error(`warning: ${warning}`);
+        for (const bundle of bundles)
+            allInstalled.push(...bundle.installed);
         console.log(JSON.stringify({
             command,
             dryRun,
             ...(catalog === undefined ? {} : summarize(catalog)),
             ...(templatesPlanned.length > 0 ? { templatesPlanned } : {}),
+            ...(bundles.length > 0 ? { templates: bundles.map(summarizeBundle) } : {}),
             installed: allInstalled.sort(),
             conflicts: allConflicts,
         }, null, 2));
@@ -183,6 +199,13 @@ function summarize(result) {
         ...(result.warnings.length > 0 ? { warnings: result.warnings } : {}),
     };
 }
+function summarizeBundle(result) {
+    return {
+        template: result.template,
+        changes: result.changes.filter((change) => change.status !== "unchanged"),
+        unchanged: result.changes.filter((change) => change.status === "unchanged").length,
+    };
+}
 // A fixed baseline for every recorded version, instead of asking npm. Rolling out a version that
 // is not published yet leaves the merge two-way, which keeps every consumer value, including the
 // package defaults a consumer never chose and would rather have replaced.

package/dist/template-bundles.d.ts

@@ -0,0 +1,21 @@
+import type { FileChange } from "./catalog-installation.js";
+import { type TemplateName } from "./workflow-catalog.js";
+export interface BundleInstallOptions {
+    /** Also overwrite files whose ownership header was removed. */
+    readonly force?: boolean;
+    /** Compute the plan and write nothing. */
+    readonly dryRun?: boolean;
+    readonly sourcePath?: string;
+    /** The version stamped into headers. Defaults to this package's. */
+    readonly packageVersion?: string;
+}
+export interface BundleInstallResult {
+    readonly template: TemplateName;
+    /** Every target of the bundle, whether it changed or not. */
+    readonly installed: readonly string[];
+    readonly changes: readonly FileChange[];
+}
+export declare function isBundleTemplate(template: TemplateName): boolean;
+/** The bundles whose files carry our ownership header in this repository. */
+export declare function installedBundles(repositoryPath: string, sourcePath: string): Promise<TemplateName[]>;
+export declare function installBundle(repositoryPath: string, template: TemplateName, sourcePath: string, options?: BundleInstallOptions): Promise<BundleInstallResult>;

package/dist/template-bundles.js

@@ -0,0 +1,108 @@
+// A bundle template stays package-managed after installation, under the catalog's header rules. It
+// counts as installed only where one of its files carries our header, so `update` never reaches a
+// repository that keeps its own headerless copies of the same paths.
+import { access, chmod, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { hasOwnershipHeader, installedVersion, packageVersion, stampVersion } from "./package-baseline.js";
+import { bundleTemplateNames, catalogTemplates } from "./workflow-catalog.js";
+const CONSUMER_OWNED = "consumer-owned: the ownership header was removed; pass --force to reclaim it";
+const carriesHeader = (target) => /\.(ya?ml|md|sh|mjs|cjs|tsv)$/.test(target);
+const normalizeEol = (text) => text.replaceAll("\r\n", "\n");
+export function isBundleTemplate(template) {
+    return bundleTemplateNames.includes(template);
+}
+/** The bundles whose files carry our ownership header in this repository. */
+export async function installedBundles(repositoryPath, sourcePath) {
+    const installed = [];
+    for (const template of bundleTemplateNames) {
+        for (const target of await bundleTargets(sourcePath, template)) {
+            if (!carriesHeader(target))
+                continue;
+            const current = await readOptional(join(repositoryPath, target));
+            if (current !== undefined && hasOwnershipHeader(current)) {
+                installed.push(template);
+                break;
+            }
+        }
+    }
+    return installed;
+}
+export async function installBundle(repositoryPath, template, sourcePath, options = {}) {
+    const version = options.packageVersion ?? await packageVersion();
+    const root = bundleRoot(sourcePath, template);
+    const targets = await bundleTargets(sourcePath, template);
+    const changes = [];
+    const writes = [];
+    for (const target of targets) {
+        const current = await readOptional(join(repositoryPath, target));
+        const text = stampVersion(normalizeEol(await readFile(join(root, target), "utf8")), version);
+        const recorded = current === undefined ? undefined : installedVersion(current);
+        const base = recorded === undefined ? { target } : { target, installedVersion: recorded };
+        if (current === text) {
+            changes.push({ ...base, status: "unchanged" });
+        }
+        else if (current !== undefined && !options.force && await consumerOwned(repositoryPath, target, current, targets)) {
+            changes.push({ target, status: "skipped", reason: CONSUMER_OWNED });
+        }
+        else if (current === undefined && documentsSkippedJson(target, changes)) {
+            // The JSON this note documents stays the consumer's, so the note would claim a file we do not own.
+            changes.push({ target, status: "skipped", reason: `documents the consumer-owned ${target.slice(0, -".md".length)}` });
+        }
+        else {
+            changes.push({ ...base, status: current === undefined ? "added" : "updated" });
+            writes.push({ target, content: text });
+        }
+    }
+    if (!options.dryRun) {
+        for (const { target, content } of writes) {
+            const destination = join(repositoryPath, target);
+            await mkdir(dirname(destination), { recursive: true });
+            await writeFile(destination, content, "utf8");
+            // A script a workflow runs by its path needs the executable bit, which a plain write never sets.
+            if (content.startsWith("#!"))
+                await chmod(destination, 0o755);
+        }
+    }
+    return { template, installed: targets, changes };
+}
+// A JSON file's header lives in its companion `<file>.md`; without that note the JSON is the consumer's.
+async function consumerOwned(repositoryPath, target, current, targets) {
+    if (carriesHeader(target))
+        return !hasOwnershipHeader(current);
+    const companion = `${target}.md`;
+    if (!targets.includes(companion))
+        return false;
+    const note = await readOptional(join(repositoryPath, companion));
+    return note === undefined || !hasOwnershipHeader(note);
+}
+// Targets are sorted, so a JSON file is always decided before the `<file>.md` that documents it.
+function documentsSkippedJson(target, changes) {
+    if (!target.endsWith(".json.md"))
+        return false;
+    const json = target.slice(0, -".md".length);
+    return changes.some((change) => change.target === json && change.status === "skipped");
+}
+function bundleRoot(sourcePath, template) {
+    const entry = catalogTemplates.find((item) => item.name === template);
+    if (entry?.bundle !== true || entry.directory === undefined)
+        throw new Error(`${template} is not a bundle template`);
+    return join(sourcePath, "templates", entry.directory);
+}
+async function bundleTargets(sourcePath, template) {
+    const root = bundleRoot(sourcePath, template);
+    const entries = await readdir(root, { recursive: true, withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(root, join(entry.parentPath, entry.name)).replaceAll("\\", "/"))
+        .sort();
+}
+async function readOptional(path) {
+    try {
+        await access(path, constants.F_OK);
+    }
+    catch {
+        return undefined;
+    }
+    return normalizeEol(await readFile(path, "utf8"));
+}

package/dist/workflow-catalog.d.ts

@@ -19,7 +19,7 @@ export interface MandatoryFile {
 }
 export declare const mandatoryFiles: readonly MandatoryFile[];
 export declare const generatedConsumerTargets: readonly [".github/workflows/agent-*.lock.yml", ".github/aw/actions-lock.json"];
-export declare const templateNames: readonly ["agentics-app-errors", "agentics-checks", "agentics-error-report", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "feature-request", "github-release", "opencode.ci.json"];
+export declare const templateNames: readonly ["agentics-app-errors", "agentics-checks", "agentics-error-report", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "bug-report", "feature-request", "github-release", "opencode.ci.json", "platform-template", "quality-gates"];
 export type TemplateName = (typeof templateNames)[number];
 export interface CatalogTemplate {
     readonly name: TemplateName;
@@ -28,5 +28,9 @@ export interface CatalogTemplate {
     readonly target?: string;
     /** Subdirectory of `templates/` holding the file. Defaults to "agentics". */
     readonly directory?: string;
+    /** Several files under `templates/<directory>/`, package-managed and refreshed by `update` where installed. */
+    readonly bundle?: boolean;
 }
 export declare const catalogTemplates: readonly CatalogTemplate[];
+/** Bundle templates: several package-managed files, refreshed by `update` where installed. */
+export declare const bundleTemplateNames: readonly TemplateName[];

package/dist/workflow-catalog.js

@@ -60,6 +60,8 @@ export const templateNames = [
     "feature-request",
     "github-release",
     "opencode.ci.json",
+    "platform-template",
+    "quality-gates",
 ];
 export const catalogTemplates = [
     { name: "agentics-app-errors", file: "agentics-app-errors.yml", description: "Daily application error report: asks Application Insights what the deployed app threw, groups it, and files one issue per distinct problem HERE, labelled bug + refine so the belt picks it up. Deterministic, no model; the report never leaves this repository, and a leak scanner withholds anything carrying an identifier." },
@@ -72,4 +74,10 @@ export const catalogTemplates = [
     { name: "feature-request", file: "feature_request.yml", description: "Feature request issue template scoped to small, well-scoped improvements (Small/Medium only; large work belongs in a planning issue).", target: ".github/ISSUE_TEMPLATE/feature_request.yml" },
     { name: "github-release", file: "github-release.yml", description: "Publishes or updates a GitHub Release with generated notes whenever a v* tag is pushed." },
     { name: "opencode.ci.json", file: "opencode.ci.json", description: "Standalone OpenCode CI config: plainconcepts provider, GLM model registration, ci-workflow-agent, and LSP defaults for consumer repositories." },
+    { name: "platform-template", file: "scripts/check-platform-conformance.mjs", directory: "platform-template", bundle: true, description: "Template sync driven by the platform contract (.platform/contract.yml): a weekly workflow that runs its sync.update command and opens or updates one pull request, and a CI guard that keeps its owned paths equal to the template outside a sync. Does nothing without a contract." },
+    { name: "quality-gates", file: "scripts/check-coverage.mjs", directory: "quality-gates", bundle: true, description: "Platform family quality gates: coverage, complexity, duplication and mutation gates, the Engineering Excellence facets, the Semgrep hygiene rules, jscpd and ZAP triage. Floors come from the app's quality.config.json; baselines stay app files." },
 ];
+/** Bundle templates: several package-managed files, refreshed by `update` where installed. */
+export const bundleTemplateNames = catalogTemplates
+    .filter((template) => template.bundle === true)
+    .map((template) => template.name);