rman 1.2.5 → 2.0.0-beta.2

package/index.js

@@ -6,47 +6,123 @@
  * per domain - CLI-only concerns (argv parsing, `--help` text, and all console/file presentation)
  * stay in `cli.ts` and the individual `commands/*.command.ts` modules, which are not exported here.
  *
- * **This is also the plugin contract.** A plugin (`rman-node`, say) is an ordinary package that
- * imports from here, so everything a command needs in order to live outside rman has to be
- * exported - the progress panel, the package filter, the branch guard, the git helper. What is
+ * **This is also the plugin contract.** A third-party plugin is an ordinary package that imports
+ * from here, so everything a command needs in order to live outside rman has to be exported - the progress panel, the package filter, the branch guard, the git helper. What is
  * *not* exported is deliberately private: config resolution internals, the expression evaluator,
  * the command registry.
  */
+/**
+ * **The `node` built-in's type augmentation, imported for the same reason `commands.ts` is.**
+ *
+ * A `declare module` augmentation applies only where the module declaring it is part of the
+ * program. The node plugin's lives in `plugins/node/augmentation/rman.augmentation.ts` and is
+ * imported by the *plugin's* entry point - which nothing here reached, so `clean`, `publish.npm`
+ * and the rest existed for rman itself and for nobody else.
+ *
+ * **Measured on a real consumer**, `@panates/rman-node`, a config package annotated with these
+ * types: `Object literal may only specify known properties, and 'clean' does not exist in type
+ * 'RmanConfig'`, plus `Property 'npm' does not exist` - ten errors across its config and its own
+ * suite. It is the identical failure the core's command keys caused when they stopped being
+ * hand-written centrally, and it reappeared the moment the plugin moved *inside* rman: until then
+ * a consumer imported `rman-node` and got the augmentation with the package.
+ *
+ * Type-only, so the emitted module is empty - imported for what it declares, not for what it does.
+ * Pinned in `docs-api.spec.ts`, which imports only from this file.
+ */
+import './plugins/node/augmentation/rman.augmentation.js';
 export { defineConfig } from './core/config.js';
 export { defineCommand } from './core/custom-command.js';
 /** Both the shape and the registry: `const m: Manifest` and `Manifest.read(dir)` - merged onto one
  *  name so a plugin can augment it the way it augments `SystemInfo`. */
+export { RmanApplication } from './core/application.js';
 export { Manifest } from './core/manifest.js';
 export { Package } from './core/package.js';
-export { definePlugin } from './core/plugin.js';
+/** The publish seam: where a package's artifact ships. The core brings `docker` (nobody's
+ *  ecosystem); npm's target is the `node` built-in's, and any other technology's is its own plugin's. */
+export { declaredTargets, shipsTo, targetsOf, unknownTargets } from './core/publish-target.js';
+export { Registry } from './core/registry.js';
 export { Repository } from './core/repository.js';
+export { Service } from './core/service.js';
+/**
+ * **`Platform` is one technology, whole**; **`Plugin` is whatever a package contributes**, platforms
+ * among them.
+ *
+ * A platform says how its packages are recognized and written, where they live, what goes on a
+ * child's PATH and how its releases are planned - `manifestProvider` is what makes one, and it is
+ * required. A plugin carries `platforms` and an `init` for anything the seams do not name yet; a
+ * bare `Platform` is accepted wherever a `Plugin` is, as sugar for the plugin that provides only it.
+ *
+ * **Both must be declared through their factory.** `loadPlugins` checks for the mark, because an
+ * rman 1.x plugin was `{ name, init }` and so is a 2.x plugin contributing nothing but an `init` -
+ * no shape test can tell them apart.
+ */
+export { basePlatform, definePlatform, definePlugin, isPlatform, } from './core/plugin.js';
 /** The numbering seam. `VersionScheme` is abstract - `highestVersion`/`highestBump`/`smallestBump`
  *  are implemented from the members around them, so a scheme states only what it must and still
  *  overrides any of the three. `SemverScheme` is exported to subclass rather than restate. */
 export { assertOneScheme, SemverScheme, semverScheme, VersionScheme } from './core/version-scheme.js';
 /** The workspace seam: how a repository's packages are found. A plugin contributes a provider
- *  (see `RmanPlugin.workspace`); the core has none, so `workspaces` is npm's idea and lives in
- *  `rman-node`. */
+ *  (see `Plugin.workspace`); the core has none, so `workspaces` is npm's idea and belongs to the
+ *  `node` built-in. */
 /** `Workspace.Layout`, `Workspace.Provider`, `Workspace.addProvider`, `Workspace.resolve`,
  *  `Workspace.findRoot` - one namespace, so a plugin can augment it. */
 export { Workspace } from './core/workspace.js';
+/**
+ * **How a command is declared** - the same API the built-ins use, so a plugin's command is declared
+ * rather than built: options as data (checked for typos), positionals named against the command
+ * string, `--config` keys derived from what the command owns, and `ArgsOf` for the handler.
+ *
+ * `declareCommand`, not `registerCommand`: the latter pushes onto a module-level registry every
+ * `runCli` walks, so a plugin using it would give its commands to repositories that never named it.
+ * Anything else puts the function in its config's `commands`.
+ *
+ * **Flat names rather than `RmanConfig.CommandOption`**, and they outlived the reason they were
+ * introduced: a second file exported a `RmanConfig` too, so the namespace holding these was
+ * unreachable from outside the package. The two are one file now and `RmanConfig` *is* exported -
+ * these stay because they are the better names for the job. A plugin author declaring a flag wants
+ * `CommandOption`; the config it happens to contribute to is not what they are naming.
+ */
+export { declareCommand } from './interfaces/rman-config.interface.js';
+export * from './commands.js';
 export * from './interfaces/rman-config.interface.js';
 export * from './services.js';
 // --- what a command needs to behave like a built-in one -----------------------------------------
 /** Branch guarding: `allowBranch`/`ignoreBranch`, so a plugin's release command refuses to run on
  *  the wrong branch exactly as `publish` and `version` do. */
-export { applyBranchGuardOptions, assertAllowedBranch, readBranchGuardOptions, } from './utils/branch-guard.js';
+export { applyBranchGuardOptions, assertAllowedBranch, branchGuardOptions, readBranchGuardOptions, } from './utils/branch-guard.js';
 /** Where a repository's locally installed binaries live - the core spells the PATH variable, a
- *  plugin says which directories go on it (see `RmanPlugin.binPaths`). */
+ *  plugin says which directories go on it (see `Plugin.binPaths`). */
 export { BinPath } from './utils/bin-path.js';
 export { exec } from './utils/exec.js';
 export { GitHelper } from './utils/git.js';
 export { LOG_LEVELS, Logger, resolveRootLogLevel } from './utils/logger.js';
 /** `--scope`/`--deps`/`--dependents`/`--private`, so a plugin's command filters packages the same
  *  way every built-in does rather than inventing its own flags. */
-export { applyPackageFilterOptions, applyRootOption, filterPackages, readPackageFilterOptions, readRootOption, } from './utils/package-filter.js';
+export { applyFromRootOption, applyPackageFilterOptions, filterPackages, fromRootOption, packageFilterOptions, readFromRootOption, readPackageFilterOptions, ROOT_SELECTOR, } from './utils/package-filter.js';
 /** The live panel `run`/`build`/`clean` print - a plugin's per-package command looks like the rest
  *  of rman instead of like a script someone bolted on. */
 export { formatDuration, ProgressPanel, } from './utils/progress-panel.js';
+/** Version stamping helpers a `Plugin.stampVersion` can delegate to - the quoted-constant
+ *  pattern most languages share, and the OCI Dockerfile label (which `version` stamps itself, since
+ *  the label's value is by specification the package's version). */
+/** A calendar version's time part (`2026.9.15-1430`) is a semver *prerelease identifier* by
+ *  construction, so anything asking "is this a preview?" has to rule it out first - `github-release`
+ *  does, and so must a publish target deciding whether a version needs its own dist-tag. Exported
+ *  because that second caller lives in a plugin. */
+/**
+ * **The `node` built-in's own surface.** It ships inside rman rather than as `rman-node`, so its
+ * services and target are named from here - a repository asks for the technology with
+ * `plugins: ['node']` (or lets detection find it) and never constructs any of this by hand.
+ *
+ * Its `.rmanrc` *keys* arrive separately, through the bare import at the top of this file - see
+ * there for why that import is not tidiness.
+ */
+export { BUILTIN_PLUGINS, builtinPluginNames, isBuiltinPlugin } from './plugins/builtins.js';
+export { NPM_TARGET, NpmPublishTarget } from './plugins/node/npm-publish-target.js';
+export { CiService } from './plugins/node/services/ci.service.js';
+export { CleanService } from './plugins/node/services/clean.service.js';
+export { PublishService } from './plugins/node/services/publish.service.js';
+export { NodeVersionPlanService } from './plugins/node/services/version-plan.service.js';
+export { isCalendarVersion } from './utils/release-version.js';
 export { runBin } from './utils/run-bin.js';
 export { OCI_VERSION_LABEL, stampVersionConstant, stampVersionLabel } from './utils/version-stamp.js';