@plexus-ms/lib 0.2.0 → 0.3.1

package/dist/propagate.js

@@ -0,0 +1,226 @@
+// propagate: bring every consumer of the presets up to a train (§ 3 PLX-Updates).
+//
+// `copier update` at every consumer site in the workspace (tenant repo roots
+// and their apps/*), then the marker synced to the answers file, lockfiles
+// refreshed where manifests moved, and the consumers' hand-owned workflows
+// pinned to the train. A consumer is touched only on its expected branch and
+// with no tracked modifications (consumers.ts). Propagation never aborts the
+// run: a failing or conflicting site is recorded and the rest continues; the
+// summary says what needs a human. Reviewing diffs and committing the
+// consumers stays human.
+//
+// The dry run is an honest preview: each consumer is cloned into a scratch
+// directory and copier-updated there from the LOCAL preset checkout at main,
+// so the diff and any conflicts show before a tag exists. That scratch work
+// goes through `Context.stage`: performed in every mode, since nothing the
+// operator owns changes.
+//
+//   plx propagate ~/dev                   # to the current train
+//   plx -n propagate ~/dev                # preview in scratch clones
+//   plx -y propagate ~/dev --train 0.66.0 # unattended: copier takes defaults
+import { join, relative } from 'node:path';
+import { bumpWorkflowRefs, hasConflictMarkers, hasUnmergedEntries, syncMarker, WORKFLOW_REF } from "./bookkeeping.js";
+import { findConsumers, presetSource } from "./consumers.js";
+import { ANSWERS_FILE, parseAnswers } from "./copier.js";
+import { MARKER_FILE } from "./marker.js";
+import { overview } from "./overview.js";
+import { run, write } from "./plan.js";
+import { TRAIN_REPOS, UPSTREAM } from "./train.js";
+/** True when nothing in the summary needs a human. */
+export const isClean = (s) => s.conflicted.length === 0 && s.failed.length === 0 && s.skipped.length === 0;
+const PREVIEW_BASE = 'ship-base';
+export async function propagate(ctx, workspace, train) {
+    const summary = { train, preview: ctx.dryRun, clean: [], conflicted: [], failed: [], skipped: [] };
+    const upstream = join(workspace, UPSTREAM);
+    const tree = await overview(ctx, workspace);
+    const upstreamDir = tree.children.find((c) => c.path === upstream);
+    const presets = TRAIN_REPOS.filter((r) => upstreamDir?.children.some((c) => c.name === r && c.template));
+    const consumers = await findConsumers(ctx, tree, presets);
+    for (const c of consumers) {
+        if (!c.skipped)
+            continue;
+        ctx.say(`⚠ ${c.rel}: ${c.skipped} — skipped (fix it, then re-run propagate)`);
+        summary.skipped.push({ path: c.rel, reason: c.skipped });
+    }
+    const active = consumers.filter((c) => !c.skipped);
+    const scratch = ctx.dryRun ? (await ctx.stage(run('mktemp', ['-d'])))?.trim() : undefined;
+    const clones = new Map();
+    /** The preview clone of a consumer, made on first use, with the base marked for diffing manifests. */
+    const cloneOf = async (consumer) => {
+        let clone = clones.get(consumer.path);
+        if (!clone) {
+            clone = join(scratch ?? '', consumer.rel);
+            await ctx.stage(run('git', ['clone', '--quiet', consumer.path, clone]));
+            await ctx.stage(run('git', ['tag', PREVIEW_BASE], { cwd: clone }));
+            clones.set(consumer.path, clone);
+        }
+        return clone;
+    };
+    // Preview commits are plain plumbing on a throwaway clone: unsigned, no hooks, a stand-in identity.
+    const previewCommit = (clone, message) => ctx
+        .stage(run('git', ['add', '-A'], { cwd: clone }))
+        .then(() => ctx.stage(run('git', [
+        '-c',
+        'commit.gpgsign=false',
+        '-c',
+        'user.name=plx',
+        '-c',
+        'user.email=plx@localhost',
+        'commit',
+        '--quiet',
+        '--no-verify',
+        '--allow-empty',
+        '-m',
+        message,
+    ], { cwd: clone })));
+    try {
+        for (const preset of presets) {
+            const sites = active.flatMap((c) => c.sites.filter((s) => s.preset === preset).map((s) => [c, s]));
+            if (sites.length === 0)
+                ctx.say(`• no consumers of ${presetSource(preset)} found under ${workspace}`);
+            for (const [consumer, site] of sites)
+                await updateSite(ctx, consumer, site, join(upstream, preset), summary, cloneOf, previewCommit);
+        }
+        await refreshLockfiles(ctx, active, summary, clones);
+        await bumpConsumerRefs(ctx, consumers, train);
+    }
+    finally {
+        if (scratch)
+            await ctx.stage(run('rm', ['-rf', scratch]));
+    }
+    return summary;
+}
+async function updateSite(ctx, consumer, site, localPreset, summary, cloneOf, previewCommit) {
+    // The repo the update lands in and the site inside it: the consumer and the
+    // site themselves, or their counterparts in the preview clone.
+    let repo = consumer.path;
+    let target = site.path;
+    try {
+        if (ctx.dryRun) {
+            ctx.say(`→ ${site.rel}: copier update (preview from ${localPreset}@main)`);
+            repo = await cloneOf(consumer);
+            target = join(repo, relative(consumer.path, site.path));
+            // Point the clone's answers at the local preset so the preview reads it;
+            // copier refuses a dirty subproject, hence the commit. Template tasks
+            // (mise install, hook setup) are the real run's business.
+            const answers = await ctx.readFile(join(site.path, ANSWERS_FILE));
+            await ctx.stage(write(join(target, ANSWERS_FILE), answers.replace(/^_src_path: .*$/m, `_src_path: ${localPreset}`)));
+            await previewCommit(repo, `plx preview: ${site.rel} reads ${localPreset} from the local checkout`);
+            await ctx.stage(run('copier', ['update', '--skip-answered', '--trust', '--defaults', '--skip-tasks', '--vcs-ref', 'main'], {
+                cwd: target,
+            }));
+        }
+        else {
+            ctx.say(`→ ${site.rel}: copier update`);
+            // Unattended, a new question takes its default; on a terminal copier asks.
+            const args = ['update', '--skip-answered', '--trust', ...(ctx.yes ? ['--defaults'] : [])];
+            await ctx.apply([run('copier', args, { cwd: target, interactive: true })]);
+        }
+    }
+    catch (error) {
+        ctx.say(`  ✗ FAILED — copier update exited nonzero${detail(error)}`);
+        summary.failed.push(site.rel);
+        return;
+    }
+    // copier applies the template diff with `git apply --3way`, which leaves
+    // unmerged index entries and inline markers when a hunk does not apply.
+    const status = await ctx.read('git', ['status', '--porcelain'], { cwd: repo });
+    let conflict = hasUnmergedEntries(status);
+    const changed = (await ctx.read('git', ['diff', '--name-only'], { cwd: repo })).split('\n').filter(Boolean);
+    for (const f of changed) {
+        const text = await ctx.readFile(join(repo, f)).catch(() => '');
+        if (hasConflictMarkers(text))
+            conflict = true;
+    }
+    await syncSiteMarker(ctx, site, target);
+    if (conflict) {
+        ctx.say('  ✗ CONFLICTS — resolve the <<<<<<< markers, then git add:');
+        summary.conflicted.push(site.rel);
+    }
+    else {
+        ctx.say('  ✓ merged clean:');
+        summary.clean.push(site.rel);
+    }
+    for (const line of status.split('\n').filter(Boolean))
+        ctx.say(`    ${line}`);
+    // Each preview site is committed in the clone so the next site's status lists only its own changes.
+    if (ctx.dryRun)
+        await previewCommit(repo, `plx preview: ${site.rel} updated`);
+}
+/** The marker's `plexus` follows the answers file's `_commit` after an update (bookkeeping.ts). */
+async function syncSiteMarker(ctx, site, target) {
+    const marker = await ctx.readFile(join(target, MARKER_FILE)).catch(() => undefined);
+    if (marker === undefined)
+        return;
+    const { commit } = parseAnswers(await ctx.readFile(join(target, ANSWERS_FILE)));
+    if (!commit)
+        return;
+    const synced = syncMarker(marker, commit);
+    if (synced === marker)
+        return;
+    ctx.say(`  marker: plexus → ${commit} in ${site.rel}/${MARKER_FILE}`);
+    const step = write(join(target, MARKER_FILE), synced);
+    if (ctx.dryRun)
+        await ctx.stage(step);
+    else
+        await ctx.apply([step]);
+}
+/** Refresh the lockfile once per consumer whose manifests the updates touched. */
+async function refreshLockfiles(ctx, consumers, summary, clones) {
+    const manifests = ['*package.json', 'pnpm-workspace.yaml'];
+    for (const c of consumers) {
+        if ((await ctx.readFile(join(c.path, 'pnpm-workspace.yaml')).catch(() => undefined)) === undefined)
+            continue;
+        const repo = ctx.dryRun ? clones.get(c.path) : c.path;
+        if (!repo)
+            continue;
+        const range = ctx.dryRun ? [PREVIEW_BASE] : [];
+        const unchanged = await ctx
+            .read('git', ['diff', '--quiet', ...range, '--', ...manifests], { cwd: repo })
+            .then(() => true)
+            .catch(() => false);
+        if (unchanged)
+            continue;
+        ctx.say(`→ ${c.rel}: pnpm install (manifests changed)`);
+        try {
+            await ctx.apply([run('mise', ['exec', '--', 'pnpm', 'install', '--reporter=silent'], { cwd: c.path })]);
+        }
+        catch (error) {
+            ctx.say(`  ✗ pnpm install failed${detail(error)}`);
+            summary.failed.push(`${c.rel}/pnpm-lock.yaml`);
+        }
+    }
+}
+/** Consumers' hand-owned workflows pin ci-cd by tag; lockstep them to the train. */
+async function bumpConsumerRefs(ctx, consumers, train) {
+    for (const c of consumers) {
+        const dir = join(c.path, '.github', 'workflows');
+        const entries = await ctx.readDir(dir).catch(() => []);
+        const files = entries
+            .filter((e) => !e.directory && /\.ya?ml$/.test(e.name))
+            .map((e) => e.name)
+            .sort();
+        if (files.length === 0)
+            continue;
+        if (c.skipped) {
+            ctx.say(`⚠ ${c.rel}: workflow refs not bumped (skipped above)`);
+            continue;
+        }
+        for (const f of files) {
+            const text = await ctx.readFile(join(dir, f));
+            if (!text.includes(WORKFLOW_REF))
+                continue;
+            const bumped = bumpWorkflowRefs(text, train);
+            if (bumped === text)
+                continue;
+            ctx.say(`→ ${c.rel}: ${f} ci-cd refs → @${train}`);
+            await ctx.apply([write(join(dir, f), bumped)]);
+        }
+    }
+}
+const detail = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const last = message.trim().split('\n').at(-1) ?? '';
+    return last && !/exited with/.test(last) ? `: ${last}` : '';
+};
+//# sourceMappingURL=propagate.js.map

package/dist/propagate.js.map

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

package/dist/requirements.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from './context.ts';
+export type PageMode = 'map' | 'module';
+export interface Scan {
+    /** `✗ <name>: line N: ...`, in page order. */
+    defects: string[];
+    /** The requirement lines of a standard module; empty for anything else. */
+    requirements: string[];
+    /** The frontmatter fields the cross-page rules need. */
+    code?: string;
+    maturity?: string;
+    binds?: string;
+    depends: string[];
+    consumes: string[];
+}
+export declare function scanPage(text: string, name: string, mode: PageMode): Scan;
+/** The requirement lines of a page, defects ignored: what `changed` compares across trains. */
+export declare const extractRequirements: (text: string) => string[];
+export declare const MAP_PAGE = "essentials/standard.md";
+export interface CompendiumCheck {
+    defects: string[];
+    contracts: number;
+    approaches: number;
+}
+/** Every module page of a compendium checkout: `<dir>/<file>`, sorted, index pages left out. */
+export declare function modulePages(ctx: Context, compendium: string): Promise<string[]>;
+export declare function checkCompendium(ctx: Context, compendium: string): Promise<CompendiumCheck>;
+//# sourceMappingURL=requirements.d.ts.map

package/dist/requirements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;AAExC,MAAM,WAAW,IAAI;IACnB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgBD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAwEzE;AAED,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,MAAM,EAA+C,CAAC;AAEzG,eAAO,MAAM,QAAQ,2BAA2B,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gGAAgG;AAChG,wBAAsB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQrF;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAuDhG"}

package/dist/requirements.js

@@ -0,0 +1,188 @@
+// The requirements check (§ 1.8 PLX), the compendium's `requirements.sh`
+// moved: a verb, not a system.
+//
+//   scanPage        one page: its defects, and for a standard module its
+//                   requirement lines, `§ <section> <text>`, in page order
+//   checkCompendium the map and every module page, plus the cross-page rules:
+//                   unique codes, known dependencies, dependencies that respect
+//                   the seams (§ 1.3 PLX)
+//
+// The map carries no requirements and no BCP 14 keyword. A module at standard
+// maturity carries its requirements as blockquoted bullets ("> - ") under
+// numbered section headings; a keyword anywhere else, a blockquote that is not
+// such a bullet, or any keyword or blockquote in a module below standard
+// maturity is a defect. The trailing "## Maintaining" section is prose
+// throughout. Extraction is structural: no classification, no heuristics.
+// `ship` compares a module's extracted lines across trains to stamp `changed`,
+// so the extractor and the linter are one function and cannot disagree.
+//
+//   plx requirements <compendium>              # lint; exit 1 on any defect
+//   plx requirements --extract contracts/app.md
+import { join } from 'node:path';
+import { CATALOG_DIRS } from "./catalog.js";
+const KEYWORD = /MUST|SHOULD|MAY/;
+/** A BCP 14 keyword in a line, the informal plurals (MUSTs, SHOULDs, MAYs) not counting. */
+const hasKeyword = (line) => KEYWORD.test(line.replace(/MUSTs|SHOULDs|MAYs/g, ''));
+/** A bracketed, comma-separated list as the frontmatter writes it: `[A, B]`. */
+const list = (value) => value
+    .replace(/^\s*\[/, '')
+    .replace(/\].*$/, '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+export function scanPage(text, name, mode) {
+    const scan = { defects: [], requirements: [], depends: [], consumes: [] };
+    const lines = text.split('\n');
+    const defect = (n, msg) => scan.defects.push(`✗ ${name}: line ${n + 1}: ${msg}`);
+    let i = 0;
+    if (lines[0] === '---') {
+        for (i = 1; i < lines.length && lines[i] !== '---'; i++) {
+            const line = lines[i] ?? '';
+            const [key = '', ...rest] = line.split(/\s+/);
+            const value = rest.join(' ');
+            if (key === 'maturity:')
+                scan.maturity = rest[0];
+            else if (key === 'code:')
+                scan.code = rest[0];
+            else if (key === 'binds:')
+                scan.binds = rest[0];
+            else if (key === 'depends:')
+                scan.depends = list(value);
+            else if (key === 'consumes:')
+                scan.consumes = list(value);
+            else if (key === 'kind:')
+                defect(i, 'kind is the folder, contracts/ or approaches/, not a field');
+        }
+        i++;
+    }
+    let inCode = false;
+    let maintaining = false;
+    let started = false;
+    let section = '';
+    for (; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (line.startsWith('```')) {
+            inCode = !inCode;
+            continue;
+        }
+        if (inCode)
+            continue;
+        if (line === '## Maintaining') {
+            maintaining = true;
+            section = '';
+            continue;
+        }
+        const heading = /^#+ § (\S+)/.exec(line);
+        if (heading) {
+            if (maintaining)
+                defect(i, 'numbered section after Maintaining');
+            section = heading[1] ?? '';
+            started = true;
+            continue;
+        }
+        if (line.startsWith('> - ')) {
+            if (mode === 'map')
+                defect(i, `requirement in the map: ${line}`);
+            else if (scan.maturity !== 'standard')
+                defect(i, `requirement in a module at ${scan.maturity} maturity: ${line}`);
+            else if (maintaining)
+                defect(i, `requirement under Maintaining: ${line}`);
+            else if (!started)
+                defect(i, 'requirement before the first § heading');
+            else
+                scan.requirements.push(`§ ${section} ${line.slice(4)}`);
+            continue;
+        }
+        if (line.startsWith('>')) {
+            defect(i, 'blockquote line is not a "> - " requirement bullet');
+            continue;
+        }
+        if (hasKeyword(line))
+            defect(i, `BCP 14 keyword outside a requirement: ${line}`);
+    }
+    if (mode === 'module') {
+        const { maturity = '', binds = '', code = '' } = scan;
+        // Reported at the page's last line, like awk's NR at END.
+        const n = text.endsWith('\n') ? lines.length - 1 : lines.length;
+        if (!/^(note|candidate|standard)$/.test(maturity))
+            defect(n - 1, `maturity must be note, candidate or standard, not "${maturity}"`);
+        if (!/^(repo|app|host|organisation)$/.test(binds))
+            defect(n - 1, `binds must be repo, app, host or organisation, not "${binds}"`);
+        if (maturity === 'note' && code !== '')
+            defect(n - 1, 'a note carries no code');
+        if (maturity !== 'note' && !/^PLX-[A-Z][A-Za-z]+$/.test(code))
+            defect(n - 1, `code must be PLX- plus one capitalised word, not "${code}"`);
+    }
+    return scan;
+}
+/** The requirement lines of a page, defects ignored: what `changed` compares across trains. */
+export const extractRequirements = (text) => scanPage(text, '', 'module').requirements;
+export const MAP_PAGE = 'essentials/standard.md';
+/** Every module page of a compendium checkout: `<dir>/<file>`, sorted, index pages left out. */
+export async function modulePages(ctx, compendium) {
+    const pages = [];
+    for (const dir of Object.keys(CATALOG_DIRS)) {
+        const entries = await ctx.readDir(join(compendium, dir));
+        for (const e of entries.filter((e) => !e.directory && e.name.endsWith('.md') && e.name !== 'index.md').sort())
+            pages.push(`${dir}/${e.name}`);
+    }
+    return pages;
+}
+export async function checkCompendium(ctx, compendium) {
+    const defects = [];
+    defects.push(...scanPage(await ctx.readFile(join(compendium, MAP_PAGE)), MAP_PAGE, 'map').defects);
+    const pages = await modulePages(ctx, compendium);
+    const scans = new Map();
+    for (const page of pages) {
+        const scan = scanPage(await ctx.readFile(join(compendium, page)), page, 'module');
+        defects.push(...scan.defects);
+        scans.set(page, scan);
+    }
+    // Module codes are unique across pages.
+    const byCode = new Map();
+    for (const [page, s] of scans)
+        if (s.code)
+            byCode.set(s.code, [...(byCode.get(s.code) ?? []), page]);
+    for (const [code, where] of byCode)
+        if (where.length > 1)
+            defects.push(`✗ duplicate module code: ${code}`);
+    // Every declared dependency names a module that exists.
+    for (const s of scans.values())
+        for (const dep of s.depends)
+            if (!byCode.has(dep))
+                defects.push(`✗ unknown module in depends: ${dep}`);
+    // Dependencies respect the seams (§ 1.3 PLX): a contract depends only on
+    // contracts, a dependency never crosses from the dev side (repo, app) to the
+    // ops side (host, organisation) or back, and what crosses a seam is listed
+    // under consumes and is a contract.
+    const kindOf = (page) => (page.startsWith('contracts/') ? 'contract' : 'approach');
+    const side = (binds) => (binds === 'repo' || binds === 'app' ? 'dev' : 'ops');
+    const kinds = new Map([...byCode].map(([code, [page = '']]) => [code, kindOf(page)]));
+    const binds = new Map([...byCode].map(([code, [page = '']]) => [code, scans.get(page)?.binds ?? '']));
+    for (const [page, s] of scans) {
+        const m = s.code ?? page.replace(/.*\//, '');
+        const kind = kindOf(page);
+        for (const c of s.consumes) {
+            if (kind === 'contract')
+                defects.push(`✗ ${m} is a contract and consumes ${c}; a contract has no other side to consume`);
+            else if (kinds.has(c) && kinds.get(c) !== 'contract')
+                defects.push(`✗ ${m} consumes ${c}, which is an approach; only a contract is consumed across a seam`);
+            else if (!kinds.has(c))
+                defects.push(`✗ ${m} consumes unknown module ${c}`);
+        }
+        for (const d of s.depends) {
+            if (!kinds.has(d))
+                continue;
+            if (kind === 'contract' && kinds.get(d) !== 'contract')
+                defects.push(`✗ ${m} is a contract and depends on the approach ${d}`);
+            if (side(s.binds ?? '') !== side(binds.get(d) ?? '') && kinds.get(d) !== 'contract')
+                defects.push(`✗ ${m} (${s.binds}) depends on ${d} (${binds.get(d)}) across the dev/ops seam; only a contract may be depended on across a seam`);
+        }
+    }
+    return {
+        defects,
+        contracts: pages.filter((p) => p.startsWith('contracts/')).length,
+        approaches: pages.filter((p) => p.startsWith('approaches/')).length,
+    };
+}
+//# sourceMappingURL=requirements.js.map

package/dist/requirements.js.map

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

package/dist/ship.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from './context.ts';
+import { type Summary } from './propagate.ts';
+export interface ShipOptions {
+    /** The workspace: the upstream umbrella and the consumers sit under it. */
+    workspace: string;
+    /** The train version; default: minor+1 over the latest, or the current one when only propagating. */
+    train?: string;
+    /** Skip the release; only propagate to the consumers. */
+    propagateOnly?: boolean;
+    /** The date stamped on the map, `YYYY-MM-DD`; default: today. */
+    today?: string;
+}
+export interface ShipResult extends Summary {
+    /** The version released, or already current when only propagating. */
+    released: boolean;
+}
+export declare function ship(ctx: Context, options: ShipOptions): Promise<ShipResult>;
+//# sourceMappingURL=ship.d.ts.map

package/dist/ship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship.d.ts","sourceRoot":"","sources":["../src/ship.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIzD,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAsB,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CASlF"}

package/dist/ship.js

@@ -0,0 +1,131 @@
+// ship: the release train (§ 1.5 PLX). Every train repo ships under ONE
+// version, tagged identically whether or not it changed:
+//
+//   preflight (every train repo on main, clean, not behind origin, the latest
+//   tags in agreement) → write the train bookkeeping (bookkeeping.ts: galaxy
+//   version, the preset's collection pin, workflow-ref examples, the map's
+//   version and timestamp, `changed` on every standard module whose extracted
+//   requirements moved) and commit it → tag every train repo → push →
+//   propagate to every consumer (propagate.ts).
+//
+// Substance commits stay human; ship writes only the mechanical bookkeeping.
+// A failure between the first tag and the last push leaves a half-tagged
+// train; the recovery is a re-run naming the same version, which skips the
+// repos already tagged and pushes the rest.
+//
+//   plx ship ~/dev                    # next train = minor+1 over the latest
+//   plx ship ~/dev --train 1.0.0      # explicit train version
+//   plx -n ship ~/dev                 # preview: list the bookkeeping, tags and
+//                                     # the propagation in scratch clones
+//   plx -y ship ~/dev                 # unattended: no prompt, copier takes defaults
+import { join } from 'node:path';
+import { bumpCollectionPin, bumpGalaxyVersion, bumpWorkflowRefs, stampChanged, stampStandard, today as todayOf, WORKFLOW_REF, } from "./bookkeeping.js";
+import { frontmatterField } from "./frontmatter.js";
+import { run, write } from "./plan.js";
+import { propagate } from "./propagate.js";
+import { extractRequirements, MAP_PAGE, modulePages } from "./requirements.js";
+import { preflightRelease, readTrain, resolveVersion, UPSTREAM } from "./train.js";
+export async function ship(ctx, options) {
+    const upstream = join(options.workspace, UPSTREAM);
+    const propagateOnly = options.propagateOnly ?? false;
+    const train = await readTrain(ctx, upstream);
+    if (!propagateOnly)
+        await preflightRelease(ctx, train);
+    const next = resolveVersion(train, options.train, propagateOnly);
+    if (!propagateOnly)
+        await release(ctx, train, next, options.today ?? todayOf());
+    const summary = await propagate(ctx, options.workspace, next);
+    return { ...summary, released: !propagateOnly };
+}
+async function release(ctx, train, next, today) {
+    ctx.say(`→ train ${train.last ?? 'none'} → ${next}`);
+    for (const repo of train.repos) {
+        if (repo.pending.length === 0)
+            ctx.say(`  ${repo.name}: no changes since ${repo.latest} — tag only`);
+        else {
+            ctx.say(`  ${repo.name} (since ${repo.latest ?? 'the beginning'}):`);
+            for (const line of repo.pending)
+                ctx.say(`    ${line}`);
+        }
+    }
+    if (!(await ctx.confirm(`tag all ${train.repos.length} repos as ${next} and push?`)))
+        throw new Error('aborted');
+    try {
+        const plan = await planBookkeeping(ctx, train, next, today);
+        await ctx.apply(plan);
+        for (const repo of train.repos) {
+            const tagged = await ctx
+                .read('git', ['rev-parse', '-q', '--verify', `refs/tags/${next}`], { cwd: repo.path })
+                .then(() => true)
+                .catch(() => false);
+            if (tagged)
+                ctx.say(`• ${repo.name}: already tagged ${next}`);
+            else
+                await ctx.apply([run('git', ['tag', '-a', next, '-m', `train ${next}`], { cwd: repo.path })]);
+            await ctx.apply([run('git', ['push', 'origin', 'main', next], { cwd: repo.path })]);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`${message}\n✗ ship stopped during the release; re-run with --train ${next} to finish it (tagged repos are skipped)`);
+    }
+}
+/** The bookkeeping writes, then one commit per train repo that has any. */
+async function planBookkeeping(ctx, train, next, today) {
+    const plan = [];
+    const touched = new Set();
+    const repo = (name) => {
+        const r = train.repos.find((r) => r.name === name);
+        if (!r)
+            throw new Error(`${name} is not a train repo`);
+        return r;
+    };
+    /** Plan a write when the transform changes the file, saying what it does; a missing file is left alone. */
+    const edit = async (r, rel, what, transform) => {
+        const path = join(r.path, rel);
+        const text = await ctx.readFile(path).catch(() => undefined);
+        if (text === undefined)
+            return;
+        const edited = transform(text);
+        if (edited === text)
+            return;
+        ctx.say(`  ${r.name}: ${rel}: ${what}`);
+        plan.push(write(path, edited));
+        touched.add(r);
+    };
+    await edit(repo('platform'), 'ansible/galaxy.yml', `version → ${next}`, (t) => bumpGalaxyVersion(t, next));
+    // Only the plexus.platform collection's pin: a second collection in the same file stays untouched.
+    await edit(repo('preset-repo-platform'), 'template/requirements.yml', `plexus.platform pin → ${next}`, (t) => bumpCollectionPin(t, next));
+    for (const r of train.repos) {
+        const files = await ctx
+            .read('git', ['grep', '-l', WORKFLOW_REF, '--', '*.yml', '*.yaml', '*.jinja'], { cwd: r.path })
+            .catch(() => '');
+        for (const f of files.split('\n').filter(Boolean))
+            await edit(r, f, `ci-cd refs → @${next}`, (t) => bumpWorkflowRefs(t, next));
+    }
+    // The map carries the train version and the date it was cut (§ 1.5 PLX); a
+    // standard module is stamped `changed` when its extracted requirement lines
+    // differ from the previous train's, read with the same extractor the
+    // compendium's check runs, so the two never disagree.
+    const comp = repo('compendium');
+    await edit(comp, MAP_PAGE, `version → ${next}, timestamp → ${today}`, (t) => stampStandard(t, next, today));
+    for (const page of await modulePages(ctx, comp.path)) {
+        const text = await ctx.readFile(join(comp.path, page));
+        if (frontmatterField(text, 'maturity') !== 'standard')
+            continue;
+        const previous = comp.tag
+            ? await ctx.read('git', ['show', `${comp.tag}:${page}`], { cwd: comp.path }).catch(() => '')
+            : '';
+        if (extractRequirements(text).join('\n') === extractRequirements(previous).join('\n'))
+            continue;
+        await edit(comp, page, `requirements changed since ${comp.latest ?? 'the beginning'} → changed: ${next}`, (t) => stampChanged(t, next));
+    }
+    for (const r of train.repos) {
+        if (!touched.has(r))
+            continue;
+        plan.push(run('git', ['add', '-A'], { cwd: r.path }));
+        plan.push(run('git', ['commit', '--quiet', '-m', `chore: train ${next} bookkeeping`], { cwd: r.path }));
+    }
+    return plan;
+}
+//# sourceMappingURL=ship.js.map