@fairgarden/distribution 0.1.0-alpha.0

package/dist/scaffold.js

@@ -0,0 +1,389 @@
+import { mkdir, writeFile, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { publishWorkflow, releaseScripts } from "./workflows.js";
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** Versions the generated projects pin, kept beside the ones this package uses. */
+export const VERSIONS = {
+    monolith: '^0.1.0-alpha.0',
+    // Provides `fg-dist`, which the release scripts and the publish workflow call.
+    distribution: '^0.1.0-alpha.0',
+    next: '^16.3.5',
+    react: '^19.3.0',
+    types: {
+        node: '^26.6.2',
+        react: '^19.3.0',
+        reactDom: '^19.3.0',
+    },
+    eslint: '^9.39.5',
+    eslintConfigNext: '^16.3.5',
+    portless: '^0.15.6',
+    typescript: '^6.0.3',
+    // Exact, because this is what `packageManager` means. The publish workflow's
+    // pnpm comes from it, so a module without one cannot build in CI.
+    pnpm: 'pnpm@10.28.0',
+};
+const GITIGNORE = `node_modules
+.next
+.turbo
+out
+build
+next-env.d.ts
+*.tsbuildinfo
+
+# derived mount points; the symlinks under src/ are what is committed
+/app/
+/pages/
+
+# generated by next dev
+AGENTS.md
+CLAUDE.md
+`;
+const TSCONFIG = {
+    compilerOptions: {
+        target: 'ES2017',
+        lib: ['dom', 'dom.iterable', 'esnext'],
+        allowJs: true,
+        skipLibCheck: true,
+        strict: true,
+        noEmit: true,
+        esModuleInterop: true,
+        module: 'esnext',
+        moduleResolution: 'bundler',
+        resolveJsonModule: true,
+        isolatedModules: true,
+        jsx: 'preserve',
+        incremental: true,
+        plugins: [{ name: 'next' }],
+    },
+    include: ['next-env.d.ts', '**/*.ts', '**/*.tsx', '.next/types/**/*.ts'],
+    exclude: ['node_modules'],
+};
+/**
+ * A repository that composes modules.
+ *
+ * The monolith app lives at `apps/monolith` so modules can be added beside it
+ * as `apps/<name>`, which is where `add-module` puts them.
+ */
+export const monolithRepo = (name, origin) => ({
+    '.gitignore': `node_modules\n.turbo\n`,
+    // Modules are linked through the workspace, so nothing here carries a
+    // version: the submodule commit is the pin and its package.json is the
+    // version. Keeping the workspace protocol stops pnpm writing one back in.
+    '.npmrc': `link-workspace-packages=true\nsave-workspace-protocol=true\n`,
+    'pnpm-workspace.yaml': `packages:\n  - "apps/*"\n  - "packages/*"\n  - "packages/*/docs"\n`,
+    'package.json': json({
+        name,
+        version: '0.1.0-alpha.0',
+        private: true,
+        ...(origin ? { repository: { type: 'git', url: origin } } : {}),
+        scripts: {
+            build: 'turbo run build',
+            // The monolith already serves every mounted app, so running their dev
+            // servers as well would be the same routes twice.
+            dev: "turbo run dev --filter=./apps/monolith --filter='./packages/*'",
+            // Each app on its own instead, for working on one in isolation or on
+            // anything the monolith cannot serve from one deployment.
+            'dev-services': 'turbo run dev:service',
+            lint: 'turbo run lint',
+        },
+        devDependencies: { turbo: '^2.11.2' },
+    }),
+    'turbo.json': json({
+        $schema: 'https://turbo.build/schema.json',
+        tasks: {
+            build: { dependsOn: ['^build'], outputs: ['.next/**', '!.next/cache/**'] },
+            lint: { dependsOn: ['^lint'] },
+            dev: { persistent: true, cache: false },
+            'dev:service': { persistent: true, cache: false },
+        },
+    }),
+    'apps/monolith/package.json': json({
+        name: `${name}-monolith`,
+        version: '0.1.0-alpha.0',
+        private: true,
+        scripts: {
+            dev: 'next dev',
+            build: 'next build',
+            start: 'next start',
+            lint: 'eslint',
+        },
+        dependencies: {
+            '@fairgarden/monolith': VERSIONS.monolith,
+            next: VERSIONS.next,
+            react: VERSIONS.react,
+            'react-dom': VERSIONS.react,
+        },
+        devDependencies: {
+            '@types/node': VERSIONS.types.node,
+            '@types/react': VERSIONS.types.react,
+            '@types/react-dom': VERSIONS.types.reactDom,
+            eslint: VERSIONS.eslint,
+            'eslint-config-next': VERSIONS.eslintConfigNext,
+            typescript: VERSIONS.typescript,
+        },
+    }),
+    'apps/monolith/next.config.ts': `import { withMonolith } from '@fairgarden/monolith'
+
+export default withMonolith(
+  {
+    // the monolith's own Next config
+  },
+  {
+    // mount name -> module, added by \`fg-dist add-module\`
+  }
+)
+`,
+    'apps/monolith/tsconfig.json': json(TSCONFIG),
+    'apps/monolith/eslint.config.mjs': `import next from 'eslint-config-next/core-web-vitals'
+
+/** @type {import('eslint').Linter.Config[]} */
+const config = [{ ignores: ['node_modules/**', '.next/**', 'app/**', 'pages/**'] }, ...next]
+
+export default config
+`,
+    'apps/monolith/.gitignore': GITIGNORE,
+    'apps/monolith/src/app/layout.tsx': `export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+`,
+    'apps/monolith/src/app/page.tsx': `export default function Home() {
+  return <main>Nothing mounted yet. Add a module with \`fg-dist add-module\`.</main>
+}
+`,
+});
+/**
+ * A repository that can be mounted into a monolith.
+ *
+ * It is an ordinary Next app; the only additions are the portability check and
+ * the lint rules that keep it mountable.
+ */
+/** `@acme/widget` -> `widget`, which is what a hostname wants. */
+const unscoped = (packageName) => packageName.replace(/^@[^/]+\//, '');
+export const moduleRepo = (packageName, origin) => ({
+    // A module releases on its own schedule, so it carries its own workflow.
+    ...publishWorkflow(packageName),
+    '.gitignore': `node_modules\n.next\n.turbo\nnext-env.d.ts\n*.tsbuildinfo\n\n# generated by next dev\nAGENTS.md\nCLAUDE.md\n`,
+    'package.json': json({
+        name: packageName,
+        version: '0.1.0-alpha.0',
+        // Not private: a module publishes itself, so that a monolith which cannot
+        // reach it as a submodule can install it as a package instead. Scoped
+        // packages publish restricted by default; say so rather than leave it to
+        // whoever reads this to remember.
+        publishConfig: { access: 'restricted' },
+        // What CI installs with — see .github/actions/publish-prepare.
+        packageManager: VERSIONS.pnpm,
+        // A module is consumed as source — its routes are read out of the package —
+        // so the tarball carries the source rather than a build.
+        files: ['app', 'lib', 'pages', 'public', 'next.config.ts'],
+        // A monolith adds this repository as a submodule, so record where it lives.
+        ...(origin ? { repository: { type: 'git', url: origin } } : {}),
+        scripts: {
+            dev: 'next dev',
+            // Served at a stable hostname instead of a port, so several apps can run
+            // at once without colliding: https://${unscoped(packageName)}.localhost
+            'dev:service': `portless ${unscoped(packageName)} next dev`,
+            build: 'next build',
+            start: 'next start',
+            lint: 'eslint',
+            // Called by .github/workflows/publish.yml, and by you — see the readme.
+            ...releaseScripts(packageName),
+        },
+        dependencies: {
+            next: VERSIONS.next,
+            react: VERSIONS.react,
+            'react-dom': VERSIONS.react,
+        },
+        devDependencies: {
+            '@fairgarden/distribution': VERSIONS.distribution,
+            '@fairgarden/monolith': VERSIONS.monolith,
+            '@types/node': VERSIONS.types.node,
+            '@types/react': VERSIONS.types.react,
+            '@types/react-dom': VERSIONS.types.reactDom,
+            eslint: VERSIONS.eslint,
+            'eslint-config-next': VERSIONS.eslintConfigNext,
+            // `dev:service` serves this at a stable hostname instead of a port.
+            portless: VERSIONS.portless,
+            typescript: VERSIONS.typescript,
+        },
+    }),
+    'next.config.ts': `import type { NextConfig } from 'next'
+import { withMonolithicPortability } from '@fairgarden/monolith'
+
+const nextConfig: NextConfig = {}
+
+// Reports anything that would not survive being mounted in a monolith.
+export default withMonolithicPortability(nextConfig)
+`,
+    'tsconfig.json': json({
+        ...TSCONFIG,
+        compilerOptions: {
+            ...TSCONFIG.compilerOptions,
+            // So this module's own files can import each other by package name,
+            // which is what keeps them resolvable once mounted.
+            paths: { [`${packageName}/*`]: ['./*'] },
+        },
+    }),
+    'eslint.config.mjs': `import next from 'eslint-config-next/core-web-vitals'
+import monolith from '@fairgarden/monolith/eslint'
+
+/** @type {import('eslint').Linter.Config[]} */
+const config = [
+  { ignores: ['node_modules/**', '.next/**'] },
+  ...next,
+  ...monolith.configs.recommended,
+]
+
+export default config
+`,
+    'lib/link.ts': `import { createHref, createLink } from '@fairgarden/monolith/link'
+
+// Use these instead of next/link so hrefs carry the mount point when this
+// module is served inside a monolith.
+export const Link = createLink('${packageName}')
+export const href = createHref('${packageName}')
+`,
+    'app/layout.tsx': `export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+`,
+    'app/page.tsx': `import { Link } from '${packageName}/lib/link'
+
+export default function Home() {
+  return (
+    <main>
+      <h1>${packageName}</h1>
+      <Link href="/">Home</Link>
+    </main>
+  )
+}
+`,
+});
+/** Write a file map, creating directories as needed. */
+export const write = async (root, files) => {
+    const written = [];
+    for (const [relative, contents] of Object.entries(files)) {
+        const full = path.join(root, relative);
+        await mkdir(path.dirname(full), { recursive: true });
+        await writeFile(full, contents);
+        written.push(relative);
+    }
+    return written.sort();
+};
+/** Whether a directory has anything in it, so `init` never writes over work. */
+export const isEmpty = async (dir) => {
+    const entries = await readdir(dir).catch(() => undefined);
+    if (!entries)
+        return true;
+    return entries.filter((entry) => entry !== '.git').length === 0;
+};
+export const readPackageName = async (root) => {
+    try {
+        const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+        return typeof pkg.name === 'string' ? pkg.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** `2024.01.15` — the date-based version a distribution is released under. */
+export const calendarVersion = (on = new Date()) => [
+    on.getUTCFullYear(),
+    String(on.getUTCMonth() + 1).padStart(2, '0'),
+    String(on.getUTCDate()).padStart(2, '0'),
+].join('.');
+/**
+ * A repository that ships a set of modules to end users.
+ *
+ * The root package.json is the distribution manifest: its version is the date
+ * it was released, and its dependencies are the modules it ships, each at a
+ * semver version. `extends` names another distribution whose modules this one
+ * inherits and may move ahead of, but never behind.
+ */
+export const distributionRepo = (name, origin, parent, { monolith = true } = {}) => {
+    // A distribution of only Next apps can deploy as one. A complex one cannot,
+    // and then each app under apps/ is deployed on its own — which is fine for
+    // an audience that already has deployment infrastructure.
+    const files = monolith
+        ? monolithRepo(name, origin)
+        : {
+            '.gitignore': `node_modules\n.turbo\n`,
+            '.npmrc': `link-workspace-packages=true\nsave-workspace-protocol=true\n`,
+            'pnpm-workspace.yaml': `packages:\n  - "apps/*"\n  - "packages/*"\n  - "packages/*/docs"\n`,
+            'turbo.json': json({
+                $schema: 'https://turbo.build/schema.json',
+                tasks: {
+                    build: {
+                        dependsOn: ['^build'],
+                        outputs: ['.next/**', '!.next/cache/**'],
+                    },
+                    lint: { dependsOn: ['^lint'] },
+                    dev: { persistent: true, cache: false },
+                },
+            }),
+        };
+    files['package.json'] = json({
+        name,
+        // End users read a date, not a semver range: it says how old their copy is.
+        version: calendarVersion(),
+        private: true,
+        ...(origin ? { repository: { type: 'git', url: origin } } : {}),
+        ...(parent ? { distribution: { extends: parent } } : {}),
+        scripts: {
+            build: 'turbo run build',
+            // With a monolith, running the mounted apps as well would serve the same
+            // routes twice. Without one, every app is its own deployment and there
+            // is nothing else to run them.
+            dev: monolith
+                ? "turbo run dev --filter=./apps/monolith --filter='./packages/*'"
+                : 'turbo run dev:service',
+            'dev-services': 'turbo run dev:service',
+            lint: 'turbo run lint',
+        },
+        // Modules go here, each pinned to the semver version this ships.
+        dependencies: parent ? { [parent]: 'latest' } : {},
+        devDependencies: { turbo: '^2.11.2' },
+    });
+    files['Readme.md'] = `# ${name}
+
+A distribution: the set of modules shipped together, released under a date-based
+version so it is obvious how old a copy is.
+
+Modules are listed in \`dependencies\`, each pinned to a semver version, and
+checked out as submodules. Add one with \`fg-dist add-module <url>\`, and see
+what has moved with \`fg-dist sync\`.
+
+## Deploying
+${monolith
+        ? `
+Every module is mounted into \`apps/monolith\`, which deploys as one Next app.
+`
+        : `
+Each app under \`apps/\` is deployed on its own. There is no monolith app,
+which is the right shape once the distribution is too complex to serve from one
+deployment — and fine for an audience that already runs deployment
+infrastructure.
+`}${parent
+        ? `
+## Extends
+
+This distribution extends \`${parent}\`. It ships that distribution's modules
+and may move ahead of them, but can never ship anything older. \`fg-dist check\`
+fails when it does${monolith ? ', and so does the monolith build' : ''}.
+`
+        : ''}`;
+    return files;
+};
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

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

package/dist/submodules.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Whether this repository ships modules, as opposed to being one.
+ *
+ * Read from `.gitmodules`, which is committed, rather than from
+ * {@link submodules}, which only reports checkouts that are actually there. A
+ * clone made without `--recurse-submodules` has the file and none of the
+ * checkouts, and treating that as a module would write a module's readme over
+ * the distribution's and let it be released as if it were one.
+ */
+export declare const isDistribution: (root: string) => boolean;
+/**
+ * Submodules that are missing their checkout.
+ *
+ * Anything that reads a module's own package.json needs to say so rather than
+ * quietly leave it out.
+ */
+export declare const uninitialised: (root: string) => string[];
+/** The repository holding the submodules, which is not the monolith directory. */
+export declare const repositoryRoot: (from: string) => string | undefined;
+export interface Submodule {
+    /** Last path segment, which is what you name on the command line. */
+    name: string;
+    /** The section name in .gitmodules, which is what config reads and writes. */
+    configName: string;
+    /** Path as recorded in .gitmodules, relative to the repository. */
+    relativePath: string;
+    path: string;
+    url: string;
+    /** The commit the repository has pinned. */
+    pinned: string;
+}
+/**
+ * Submodules as `.gitmodules` records them, with the commit each is pinned to.
+ *
+ * Uninitialised submodules are left out — there is nothing to inspect until
+ * they are checked out.
+ */
+export declare const submodules: (root: string) => Submodule[];
+export type ReleaseKind = 'major' | 'minor' | 'patch';
+export interface SubmoduleState {
+    submodule: Submodule;
+    /** The commit checked out right now, which a bump changes. */
+    head: string;
+    /** Version pinned right now, when a tag names it. */
+    current: string | undefined;
+    /** Whether that tag is the pinned commit rather than an ancestor of it. */
+    exact: boolean;
+    /** Newer version tags, newest first. */
+    available: string[];
+    /** The newest upgrade of each kind that is available. */
+    upgrades: Partial<Record<ReleaseKind, string>>;
+    /** Commits on the tracked branch that no version tag covers yet. */
+    untagged: number;
+    /** Uncommitted changes, which make moving the pin unsafe. */
+    dirty: boolean;
+    /** Whether the remote was reachable, when a fetch was attempted. */
+    fetched: boolean | undefined;
+}
+/**
+ * Compare a submodule's pinned commit against the versions its repository has.
+ *
+ * Only tags that name a version are considered an upgrade. Commits past the
+ * newest tag are counted and reported, but never bumped to — a commit carries
+ * no statement about what changed, which is the whole point of the version.
+ */
+export declare const inspect: (submodule: Submodule, { fetch }?: {
+    fetch?: boolean;
+}) => SubmoduleState;
+/**
+ * The version a bump should move to, or undefined when there is nothing to do.
+ *
+ * Major upgrades are held back unless asked for: they are the ones that need a
+ * person to read a changelog first.
+ */
+export declare const target: (state: SubmoduleState, { major }?: {
+    major?: boolean;
+}) => string | undefined;
+/**
+ * Record a different URL for a submodule.
+ *
+ * `.gitmodules` is what gets committed, and `submodule sync` copies it into the
+ * local config so the existing checkout uses it too. The caller commits.
+ */
+export declare const setUrl: (root: string, submodule: Submodule, url: string) => void;
+/**
+ * Whether a remote can be read with no credentials at all.
+ *
+ * This is the question a build host asks. Prompting is disabled so a private
+ * repository fails immediately instead of waiting for a password nobody is
+ * there to type.
+ */
+export declare const isPublic: (url: string, timeout?: number) => boolean;
+/** Move a submodule's checkout to a tag. The caller commits the new pointer. */
+export declare const moveTo: (submodule: Submodule, tag: string) => void;
+//# sourceMappingURL=submodules.d.ts.map

package/dist/submodules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submodules.d.ts","sourceRoot":"","sources":["../src/submodules.ts"],"names":[],"mappings":"AAqBA;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,OAEyC,CAAA;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAAM,EAOlD,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SACV,CAAA;AAE7C,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,SAAS,EAgClD,CAAA;AAgBD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;AAErD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,SAAS,CAAA;IACpB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAA;IAC9C,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAClB,WAAW,SAAS,EACpB,YAAkB;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,KACzC,cA6DF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GACjB,OAAO,cAAc,EACrB,YAAmB;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,KAC1C,MAAM,GAAG,SASX,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,WAAW,SAAS,EAAE,KAAK,MAAM,KAAG,IAYxE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,gBAAgB,KAAG,OAoBxD,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,MAAM,GAAI,WAAW,SAAS,EAAE,KAAK,MAAM,KAAG,IAa1D,CAAA"}