@fairgarden/distribution 0.1.0-alpha.3 → 0.1.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -2,29 +2,10 @@
 
 <!-- fg:version -->
 
-Version **0.1.0-alpha.3**
+Version **0.1.0-alpha.5**
 
 <!-- /fg:version -->
 
-<!-- fg:releasing -->
-
-## Releasing
-
-This module releases on its own. `0.1.0-alpha.3` is what main is working towards,
-not what is published — the version here is always the next one.
-
-1. **Publish it.** Run the *Publish* workflow from the Actions tab, picking the
-   dist tag. It refuses if that version is already on npm.
-2. **Move it on.** `pnpm release` — opens a pull request bumping this branch
-   to `0.1.0-alpha.4`, or `pnpm release --id rc` to change
-   identifier. A prerelease gets no maintenance branch; there is no released
-   line behind it yet.
-
-Every push to main publishes `@fairgarden/distribution@canary`. A canary is not a release and
-carries no promise; it is there so main can be tried without a checkout.
-
-<!-- /fg:releasing -->
-
 Ship a set of versioned modules together.
 
 End users do not care about semver — they want to know how old their copy is,
@@ -95,3 +76,30 @@ fg-dist prerelease --major   # start the next line on a branch, leaving main alo
 
 Mounting a distribution's apps into one Next deployment is a separate concern,
 handled by `@fairgarden/monolith`.
+
+<!-- fg:releasing -->
+
+## Releasing
+
+This module releases on its own. `0.1.0-alpha.5` is what main is working towards,
+not what is published — the version here is always the next one. Its release
+notes are the top section of `CHANGELOG.md`, where every pull request adds a
+line linking itself.
+
+1. **Publish it.** Run the *Publish* workflow from the Actions tab, picking the
+   dist tag. It refuses if that version is already on npm. Once it is out, open
+   pull requests are held — their changelog check fails — so nothing is noted
+   under a version that has already shipped.
+2. **Move it on.** `pnpm release` opens a pull request moving main to
+   `0.1.0-alpha.6` and starting its section of the changelog, or
+   `pnpm release --id rc` to change identifier. Merging it lifts the hold. A
+   prerelease gets no maintenance branch; there is no released line behind it
+   yet.
+
+A held pull request goes on once it is brought up to date with main and its
+line is moved into the new version's section.
+
+Every push to main publishes `@fairgarden/distribution@canary`. A canary is not a release and
+carries no promise; it is there so main can be tried without a checkout.
+
+<!-- /fg:releasing -->

package/dist/cli.js

@@ -5,7 +5,8 @@ import { mkdir, readFile } from 'node:fs/promises';
 import { addModule } from "./add-module.js";
 import { extractModule } from "./extract.js";
 import { writeReadmes } from "./readme.js";
-import { writeDistributionChangelogCheck, writeDistributionWorkflow, writeWorkflows } from "./workflows.js";
+import { verify } from "./verify.js";
+import { toolRelease, writeDistributionChecks, writeDistributionWorkflow, writeWorkflows } from "./workflows.js";
 import { writeOverrides } from "./overrides.js";
 import { checkReleasable, planRelease, readRelease, release, releaseDistribution, reportToActions as reportRelease, startPrerelease, } from "./release.js";
 import { reportToActions as reportCanary, stampCanary } from "./canary.js";
@@ -27,6 +28,7 @@ for (const stream of [process.stdout, process.stderr]) {
     });
 }
 const USAGE = `Usage: fg-dist <command> [options]
+       pnpm dist <command> [options], in a repository fg-dist set up
 
 Commands:
   init <kind> [dir]    Scaffold a repository; kind is "distribution", "monolith" or "module"
@@ -41,6 +43,7 @@ Commands:
   release              Move a module on from the release it just published
   prerelease           Start the next line on a branch, leaving main where it is
   check                Fail when this ships anything older than what it extends
+  verify               Fail when a file fg-dist writes no longer says what is true (CI)
   inherit              Add the modules the distribution this extends ships, and this does not
   sync                 Report which modules have newer versions available
   bump [name...]       Move modules to their newest non-major version; a fork merges it
@@ -73,6 +76,7 @@ Options:
   --no-git             Skip "git init" when scaffolding
   --url <git-url>      Remote the scaffolded repository will live at (init)
   --extends <name>     Distribution the scaffolded one extends (init distribution)
+  --copyright <holder> Who holds the copyright on its MIT license (init; default: git user.name)
   --separate           Scaffold a distribution whose apps deploy separately
   --ssh                Record a submodule's URL as given, without rewriting it
   --no-verify          Skip checking whether the https urls can be cloned
@@ -116,6 +120,7 @@ const parseArgs = (argv) => {
         pr: undefined,
         repo: undefined,
         direct: false,
+        copyright: undefined,
     };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -177,6 +182,9 @@ const parseArgs = (argv) => {
         else if (arg === '--no-push') {
             args.push = false;
         }
+        else if (arg === '--copyright') {
+            args.copyright = argv[++index];
+        }
         else if (arg === '--direct') {
             args.direct = true;
         }
@@ -305,6 +313,28 @@ const modulesFor = (cwd, names) => {
     }
     return { root, modules };
 };
+/**
+ * Bring a distribution's readme up to what a command just changed.
+ *
+ * Its table names every module's version and pin, so a command that moves one
+ * leaves it stale — and \`verify\` fails the pull request that forgot. Only the
+ * distribution's own: a module's readme is the module's, and writing into one
+ * would leave its submodule dirty.
+ */
+const refreshReadme = async (root) => {
+    if (!isDistribution(root))
+        return;
+    try {
+        const { updates } = await writeReadmes(root, { modules: false });
+        for (const update of updates.filter((each) => each.changed)) {
+            process.stdout.write(`${path.relative(root, update.file)} lists what it ships now.\n`);
+        }
+    }
+    catch (error) {
+        process.stderr.write(`The readme was not updated: ${error instanceof Error ? error.message : String(error)}\n` +
+            'Run `pnpm dist readme` once that is sorted.\n');
+    }
+};
 const pad = (values) => values.reduce((widest, value) => Math.max(widest, value.length), 0);
 const main = async () => {
     const args = parseArgs(process.argv.slice(2));
@@ -328,11 +358,22 @@ const main = async () => {
         // A module is consumed as a submodule, so record the URL it will be
         // cloned from in the form a keyless clone can use.
         const origin = args.url ? (args.ssh ? args.url : toHttps(args.url)) : undefined;
+        // Who holds the copyright on the MIT license it starts under: as given, or
+        // whoever git says is making it.
+        let copyright = args.copyright;
+        if (!copyright) {
+            try {
+                copyright = execFileSync('git', ['config', 'user.name'], { encoding: 'utf8' }).trim() || undefined;
+            }
+            catch {
+                copyright = undefined;
+            }
+        }
         const files = kind === 'distribution'
-            ? distributionRepo(name, origin, args.extends, { monolith: !args.separate })
+            ? distributionRepo(name, origin, args.extends, { monolith: !args.separate, copyright })
             : kind === 'monolith'
-                ? monolithRepo(name, origin)
-                : moduleRepo(name, origin);
+                ? monolithRepo(name, origin, { copyright })
+                : moduleRepo(name, origin, { copyright });
         const written = await write(target, files);
         if (args.git) {
             try {
@@ -363,8 +404,8 @@ const main = async () => {
         process.stdout.write(kind === 'module'
             ? 'Next: pnpm install, then commit and push so a distribution can add it.\n'
             : args.extends && kind === 'distribution'
-                ? `Next: pnpm install, then \`fg-dist inherit\` to ship what ${args.extends} ships.\n`
-                : 'Next: pnpm install, then `fg-dist add-module <url>` to ship a module.\n');
+                ? `Next: pnpm install, then \`pnpm dist inherit\` to ship what ${args.extends} ships.\n`
+                : 'Next: pnpm install, then `pnpm dist add-module <url>` to ship a module.\n');
         return 0;
     }
     if (args.command === 'add-module') {
@@ -401,7 +442,7 @@ const main = async () => {
         else if (result.overridesError) {
             process.stderr.write(`\nThe module is added, but the workspace overrides were not updated:\n` +
                 `  ${result.overridesError}\n` +
-                'Run `fg-dist overrides` once that is sorted.\n');
+                'Run `pnpm dist overrides` once that is sorted.\n');
         }
         if (result.mounted && result.monolithConfig) {
             process.stdout.write(`Mounted at /${result.mount} in ${path.relative(args.cwd, result.monolithConfig)}\n`);
@@ -426,6 +467,9 @@ const main = async () => {
         if (result.turbo) {
             process.stdout.write("turbo.json: the monolith's build waits for its libraries, not its own build\n");
         }
+        const root = repositoryRoot(args.cwd);
+        if (root)
+            await refreshReadme(root);
         process.stdout.write(result.monolithPackageJson
             ? '\nRun pnpm install and `fg-monolith merge-package-json`.\n'
             : '\nRun pnpm install.\n');
@@ -451,7 +495,7 @@ const main = async () => {
         if (args.check) {
             process.stderr.write(`\n${changed.length} readme(s) are out of date:\n${changed
                 .map((update) => `  ${path.relative(root, update.file)}`)
-                .join('\n')}\nRun \`fg-dist readme\` to update them.\n`);
+                .join('\n')}\nRun \`pnpm dist readme\` to update them.\n`);
             return 1;
         }
         process.stdout.write(`\nUpdated:\n${changed
@@ -478,7 +522,7 @@ const main = async () => {
                     '  "publishConfig": { "access": "public" }\n');
             }
             process.stdout.write('\nIt publishes the manifest, recording every module it ships, and its policy. ' +
-                'Version it with `fg-dist release`, then run the workflow.\n');
+                'Version it with `pnpm release`, then run the workflow.\n');
             return 0;
         }
         const updates = await writeWorkflows(root, {
@@ -486,10 +530,10 @@ const main = async () => {
             dryRun: args.dryRun,
             names: args.names,
         });
-        // The distribution checks its own changelog too, for policy changes —
-        // unless only some modules were named.
+        // The distribution has its own checks too — the changelog for policy
+        // changes, and what fg-dist writes — unless only some modules were named.
         if (isDistribution(root) && args.names.length === 0) {
-            updates.push(await writeDistributionChangelogCheck(root, { force: args.force, dryRun: args.dryRun }));
+            updates.push(await writeDistributionChecks(root, { force: args.force, dryRun: args.dryRun }));
         }
         if (updates.length === 0) {
             process.stdout.write('No modules here. Run this in a distribution, which is where the modules are.\n');
@@ -501,6 +545,14 @@ const main = async () => {
                 ? `${update.relativePath}  has one already\n`
                 : `${update.relativePath}  ${update.files.join(', ')}\n`);
         }
+        // A module's CI installs fg-dist from npm, so what these workflows run has
+        // to be in a release it can install.
+        const tool = await toolRelease();
+        if (tool && tool.floor !== tool.own) {
+            process.stderr.write(`\nfg-dist ${tool.own} is not released, so modules are given ^${tool.floor}, the newest that is.\n` +
+                `Whatever these workflows run that is new since then fails in the modules' CI until\n` +
+                `${tool.own} is published. Publish it, then run this again to move them up to it.\n`);
+        }
         if (written.length === 0) {
             process.stdout.write('\nEvery module already publishes. Pass --force to overwrite the workflows.\n');
             return 0;
@@ -564,7 +616,7 @@ const main = async () => {
         }
         if (args.check) {
             process.stderr.write(`\n${path.relative(root, file)} does not match the modules here.\n` +
-                'Run `fg-dist overrides` to update it.\n');
+                'Run `pnpm dist overrides` to update it.\n');
             return 1;
         }
         process.stdout.write(`\nUpdated ${path.relative(root, file)}. Run \`pnpm install\` to take it up.\n`);
@@ -633,7 +685,7 @@ const main = async () => {
                             ? `${plan.maintenance.branch} keeps ${released.split('.').slice(0, 2).join('.')}.x\n`
                             : 'stays on this line; nothing branches off\n'));
                 }
-                process.stdout.write(`\nOr \`fg-dist prerelease --major\` to start the next line beside main, ` +
+                process.stdout.write(`\nOr \`pnpm dist prerelease --major\` to start the next line beside main, ` +
                     'without\nmoving main off this one.\n');
                 return 1;
             }
@@ -735,7 +787,7 @@ const main = async () => {
                 process.stdout.write('turbo.json builds the policy once, before each service that uses it.\n');
                 return 0;
             }
-            process.stdout.write(`${args.check ? 'turbo.json is missing' : 'Wrote'} ${differ.join(', ')}${args.check ? '; run fg-dist policy setup.' : ' into turbo.json.'}\n`);
+            process.stdout.write(`${args.check ? 'turbo.json is missing' : 'Wrote'} ${differ.join(', ')}${args.check ? '; run pnpm dist policy setup.' : ' into turbo.json.'}\n`);
             return args.check ? 1 : 0;
         }
         process.stderr.write('Usage: fg-dist policy <build|test|use|setup>\n');
@@ -763,6 +815,23 @@ const main = async () => {
             `than ${report.parent?.name}@${report.parent?.version}.\n`);
         return 0;
     }
+    if (args.command === 'verify') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const checks = await verify(root);
+        const width = pad(checks.map((check) => check.what));
+        for (const check of checks) {
+            if (check.ok) {
+                process.stdout.write(`ok     ${check.what}\n`);
+                continue;
+            }
+            const problem = (check.problem ?? '').split('\n').join(`\n       ${' '.repeat(width)}  `);
+            process.stderr.write(`stale  ${check.what.padEnd(width)}  ${problem}\n` +
+                (check.fix ? `       ${' '.repeat(width)}  Run \`${check.fix}\`.\n` : ''));
+        }
+        return checks.every((check) => check.ok) ? 0 : 1;
+    }
     if (args.command === 'extract') {
         const [target] = args.names;
         if (!target) {
@@ -791,8 +860,11 @@ const main = async () => {
         if (result.overridesError) {
             process.stderr.write(`\nThe module is extracted, but the workspace overrides were not updated:\n` +
                 `  ${result.overridesError}\n` +
-                'Run `fg-dist overrides` once that is sorted.\n');
+                'Run `pnpm dist overrides` once that is sorted.\n');
         }
+        const root = repositoryRoot(args.cwd);
+        if (root)
+            await refreshReadme(root);
         process.stdout.write(`origin is ${result.url}\n`);
         if (result.rewritten) {
             process.stdout.write(`(rewritten from ${args.url}; a submodule is cloned without an SSH key)\n`);
@@ -863,7 +935,7 @@ const main = async () => {
                 process.stdout.write(`  ${state.submodule.relativePath}  ${state.submodule.url}` +
                     `  ->  ${toHttps(state.submodule.url)}\n`);
             }
-            process.stdout.write('Run `fg-dist use-https` to rewrite them. They also have to be ' +
+            process.stdout.write('Run `pnpm dist use-https` to rewrite them. They also have to be ' +
                 'readable without credentials, which means public.\n');
         }
         // A pin the remote does not have breaks every other clone, a build host's first.
@@ -874,7 +946,7 @@ const main = async () => {
             for (const state of unpushed) {
                 process.stdout.write(`  ${state.submodule.relativePath}  ${state.head.slice(0, 7)}\n`);
             }
-            process.stdout.write('Push them — `fg-dist contribute <name>` does, for a change on its way upstream.\n');
+            process.stdout.write('Push them — `pnpm dist contribute <name>` does, for a change on its way upstream.\n');
         }
         // A fork whose work upstream has taken can go back to upstream.
         const returnable = states.filter((state) => canReturn(state));
@@ -883,7 +955,7 @@ const main = async () => {
             for (const state of returnable) {
                 process.stdout.write(`  ${state.submodule.relativePath}  in ${canReturn(state)}\n`);
             }
-            process.stdout.write('Keep them, or `fg-dist unfork <name>` to go back to upstream.\n');
+            process.stdout.write('Keep them, or `pnpm dist unfork <name>` to go back to upstream.\n');
         }
         // An extension may move ahead of what it extends, never behind it.
         const extendsReport = inspectExtends(root);
@@ -913,9 +985,9 @@ const main = async () => {
         // A major is only held back when it is newer than the non-major target.
         const held = upgradable.filter((state) => state.upgrades.major !== undefined);
         process.stdout.write(`\n${upgradable.length} module(s) have newer versions. `);
-        process.stdout.write('Run `fg-dist bump` to take them');
+        process.stdout.write('Run `pnpm dist bump` to take them');
         process.stdout.write(held.length > 0
-            ? `, or \`fg-dist bump --major\` to include the ${held.length} major upgrade(s).\n`
+            ? `, or \`pnpm dist bump --major\` to include the ${held.length} major upgrade(s).\n`
             : '.\n');
         return 0;
     }
@@ -964,7 +1036,7 @@ const main = async () => {
             try {
                 const done = integrate(root, state, to, { push: args.push });
                 process.stdout.write(done.how === 'moved'
-                    ? `${line}  (fork: upstream has all of it; \`fg-dist unfork ${state.submodule.name}\` goes back)\n`
+                    ? `${line}  (fork: upstream has all of it; \`pnpm dist unfork ${state.submodule.name}\` goes back)\n`
                     : `${line}  (fork: merged${done.pushed ? `, pushed to ${done.pushed}` : ', not pushed'})\n`);
             }
             catch (error) {
@@ -972,6 +1044,8 @@ const main = async () => {
                 process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
             }
         }
+        if (!args.dryRun)
+            await refreshReadme(root);
         process.stdout.write(args.dryRun
             ? '\nDry run; nothing moved.\n'
             : '\nSubmodule pointers moved. Commit them to record the new versions.\n');
@@ -991,10 +1065,23 @@ const main = async () => {
         for (const module of result.blocked) {
             process.stderr.write(`${module.path} has something in it already, so ${module.name} was not added there.\n`);
         }
+        // The parent's notice goes with what is built on it.
+        const license = result.license;
+        if (license.how === 'merged') {
+            process.stdout.write(`LICENSE carries ${result.parent}'s copyright too: ${license.lines.join('; ')}\n`);
+        }
+        else if (license.how === 'copied') {
+            process.stdout.write(`${license.file} keeps ${result.parent}'s license, which is not this one's.\n`);
+        }
+        else if (license.how === 'none') {
+            process.stdout.write(`${result.parent} publishes no license to carry.\n`);
+        }
         if (result.added.length === 0 && result.blocked.length === 0) {
             process.stdout.write(`Ships everything ${result.parent}@${result.parentVersion} ships already.\n`);
             return 0;
         }
+        if (!args.dryRun && result.added.length > 0)
+            await refreshReadme(root);
         process.stdout.write(args.dryRun
             ? '\nDry run; nothing added.\n'
             : `\nShips what ${result.parent}@${result.parentVersion} ships. Run pnpm install, then commit.\n`);
@@ -1058,11 +1145,12 @@ const main = async () => {
     if (args.command === 'fork') {
         const [name, url] = args.names;
         if (!name || !url) {
-            process.stderr.write('fork needs a module and the url of your fork: fg-dist fork <name> <url>\n');
+            process.stderr.write('fork needs a module and the url of your fork: pnpm dist fork <name> <url>\n');
             return 1;
         }
         const { root, modules } = modulesFor(args.cwd, [name]);
         const result = forkModule(root, modules[0], url, { ssh: args.ssh, push: args.push });
+        await refreshReadme(root);
         process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url}\n` +
             `forked from ${result.upstream}, which .gitmodules records as its upstream\n`);
         if (result.rewritten) {
@@ -1072,13 +1160,13 @@ const main = async () => {
             ? `Pinned commit pushed to ${result.branch}, where everything this distribution pins in the fork lives.\n`
             : 'Nothing pushed. The pinned commit has to be on the fork before anyone else can check it out.\n');
         process.stdout.write(`\nNext: make the change on a branch in ${modules[0].relativePath}, then ` +
-            `\`fg-dist contribute ${modules[0].name}\`.\nCommit .gitmodules and ${modules[0].relativePath} here.\n`);
+            `\`pnpm dist contribute ${modules[0].name}\`.\nCommit .gitmodules and ${modules[0].relativePath} here.\n`);
         return 0;
     }
     if (args.command === 'contribute') {
         const [name] = args.names;
         if (!name) {
-            process.stderr.write('contribute needs a module: fg-dist contribute <name>\n');
+            process.stderr.write('contribute needs a module: pnpm dist contribute <name>\n');
             return 1;
         }
         const { root, modules } = modulesFor(args.cwd, [name]);
@@ -1087,6 +1175,7 @@ const main = async () => {
             process.stdout.write(`Would push ${result.branch} and open a pull request into ${describeRemote(result.repository)} ${result.base}.\n`);
             return 0;
         }
+        await refreshReadme(root);
         process.stdout.write(`Pushed ${result.branch}.\n`);
         if (result.pinnedOn)
             process.stdout.write(`Pinned commit kept on ${result.pinnedOn}, which outlives the pull request's branch.\n`);
@@ -1111,12 +1200,13 @@ const main = async () => {
     if (args.command === 'unfork') {
         const [name] = args.names;
         if (!name) {
-            process.stderr.write('unfork needs a module: fg-dist unfork <name>\n');
+            process.stderr.write('unfork needs a module: pnpm dist unfork <name>\n');
             return 1;
         }
         const { root, modules } = modulesFor(args.cwd, [name]);
         const state = inspect(modules[0], { fetch: args.fetch });
         const result = unforkModule(root, state, { to: args.to, major: args.major, force: args.force });
+        await refreshReadme(root);
         process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url} again, at ${result.to}.\n` +
             `Commit .gitmodules and ${modules[0].relativePath} here. The fork itself is left as it is.\n`);
         return 0;