tegami 0.2.1 → 1.0.0-beta.1

package/dist/providers/npm.js

@@ -1,334 +1,2 @@
-import { i as isNodeError, n as execFailure } from "../error-DNy8R5ue.js";
-import { n as packageManifestSchema, r as pnpmWorkspaceSchema } from "../schemas-BdUlXfSu.js";
-import { n as WorkspacePackage } from "../graph-DrzluXw8.js";
-import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { x } from "tinyexec";
-import * as semver from "semver";
-import z from "zod";
-import { load } from "js-yaml";
-import { glob } from "tinyglobby";
-import { detect } from "package-manager-detector";
-//#region src/providers/npm.ts
-const DEP_FIELDS = [
-	"dependencies",
-	"devDependencies",
-	"peerDependencies",
-	"optionalDependencies"
-];
-var NpmPackage = class extends WorkspacePackage {
-	path;
-	manifest;
-	manager = "npm";
-	constructor(path, manifest) {
-		super();
-		this.path = path;
-		this.manifest = manifest;
-	}
-	get name() {
-		return this.manifest.name;
-	}
-	get version() {
-		return this.manifest.version ?? "0.0.0";
-	}
-	async write() {
-		await writeFile(path.join(this.path, "package.json"), `${JSON.stringify(this.manifest, null, 2)}\n`);
-	}
-	initDraft() {
-		const defaults = super.initDraft();
-		if (this.manifest.publishConfig?.tag) {
-			defaults.npm ??= {};
-			defaults.npm.distTag ??= this.manifest.publishConfig.tag;
-		}
-		return defaults;
-	}
-};
-function parseDependencySpec(context, dependent, name, range) {
-	const { graph } = context;
-	if (range.startsWith("workspace:")) return {
-		range: range.slice(10),
-		linked: graph.get(`npm:${name}`),
-		protocol: "workspace"
-	};
-	if (range.startsWith("file:")) {
-		let target = path.resolve(dependent.path, range.slice(5));
-		if (path.basename(target) === "package.json") target = path.dirname(target);
-		return {
-			protocol: "file",
-			raw: range,
-			linked: graph.getPackages().find((pkg) => pkg instanceof NpmPackage && pkg.path === target)
-		};
-	}
-	if (range.startsWith("npm:")) {
-		const spec = range.slice(4);
-		const separator = spec.lastIndexOf("@");
-		if (separator <= 0) return;
-		const alias = spec.slice(0, separator);
-		return {
-			alias,
-			linked: graph.get(`npm:${alias}`),
-			range: spec.slice(separator + 1),
-			protocol: "npm"
-		};
-	}
-	return {
-		linked: graph.get(`npm:${name}`),
-		range
-	};
-}
-function formatDependencySpec(spec) {
-	if (spec.protocol === "workspace") return `workspace:${spec.range}`;
-	if (spec.protocol === "file") return spec.raw;
-	if (spec.protocol === "npm") return `npm:${spec.alias}@${spec.range}`;
-	return spec.range;
-}
-const packageLockSchema = z.object({
-	id: z.string(),
-	distTag: z.string().optional()
-});
-function npm({ client: defaultClient, onBreakPeerDep = "set", updateLockFile = true, bumpDep: getBumpDepType = ({ kind }) => {
-	switch (kind) {
-		case "dependencies":
-		case "optionalDependencies": return "patch";
-		case "devDependencies": return false;
-		case "peerDependencies":
-			if (onBreakPeerDep === "ignore") return false;
-			return "major";
-	}
-} } = {}) {
-	let active = false;
-	let client;
-	return {
-		name: "npm",
-		enforce: "pre",
-		async init() {
-			if (defaultClient) client = defaultClient;
-			else client = (await detect({ cwd: this.cwd }))?.name ?? "npm";
-			this.npm = { client };
-		},
-		async resolve() {
-			await discoverNpmPackages(this.cwd, (pkg) => this.graph.add(pkg));
-			active = this.graph.getPackages().some((pkg) => pkg instanceof NpmPackage);
-		},
-		async publishPreflight({ pkg }) {
-			if (!(pkg instanceof NpmPackage)) return;
-			return { publish: pkg.manifest.private !== true && !await isPackagePublished(pkg) };
-		},
-		initPublishLock({ lock, draft }) {
-			for (const [id, pkg] of draft.getPackageDrafts()) {
-				if (!pkg.npm) continue;
-				lock.write("npm:packages", {
-					id,
-					distTag: pkg.npm.distTag
-				});
-			}
-		},
-		initPublishPlan({ lock, plan }) {
-			let data;
-			while (data = lock.read("npm:packages")) {
-				const parsed = packageLockSchema.safeParse(data).data;
-				if (!parsed) continue;
-				const packagePlan = plan.packages.get(parsed.id);
-				if (!packagePlan) continue;
-				packagePlan.npm = { distTag: parsed.distTag };
-			}
-		},
-		async publish({ pkg, plan }) {
-			if (!(pkg instanceof NpmPackage)) return;
-			return publish(client, pkg, plan.packages.get(pkg.id)?.npm?.distTag);
-		},
-		initDraft(plan) {
-			if (!active) return;
-			plan.addPolicy(depsPolicy(this, getBumpDepType));
-		},
-		async applyDraft(draft) {
-			if (!active) return;
-			const { graph } = this;
-			const writes = [];
-			for (const pkg of graph.getPackages()) {
-				if (!(pkg instanceof NpmPackage)) continue;
-				const plan = draft.getPackageDraft(pkg.id);
-				if (plan) pkg.manifest.version = plan.bumpVersion(pkg);
-			}
-			for (const pkg of graph.getPackages()) {
-				if (!(pkg instanceof NpmPackage)) continue;
-				for (const field of DEP_FIELDS) {
-					const dependencies = pkg.manifest[field];
-					if (!dependencies) continue;
-					for (const [k, v] of Object.entries(dependencies)) {
-						const spec = parseDependencySpec(this, pkg, k, v);
-						if (!spec?.linked || spec.protocol === "workspace" || spec.protocol === "file") continue;
-						if (!semver.validRange(spec.range)) continue;
-						if (semver.satisfies(spec.linked.version, spec.range)) continue;
-						let updatedRange;
-						const isPeer = field === "peerDependencies";
-						if (isPeer && onBreakPeerDep === "ignore") continue;
-						else if (isPeer && onBreakPeerDep === "set") updatedRange = spec.linked.version;
-						else if (isPeer && onBreakPeerDep === "error") throw new Error(`[Tegami] the version of "${spec.linked.name}" is beyond its peer dependency constraint "${v}" in package "${pkg.name}", please update the constraint to satisfy.`);
-						else if (spec.range.startsWith("^")) updatedRange = `^${spec.linked.version}`;
-						else if (spec.range.startsWith("~")) updatedRange = `~${spec.linked.version}`;
-						else updatedRange = spec.linked.version;
-						dependencies[k] = formatDependencySpec({
-							...spec,
-							range: updatedRange
-						});
-					}
-				}
-				writes.push(pkg.write());
-			}
-			await Promise.all(writes);
-		},
-		cli: { async draftApplied() {
-			if (!active || !updateLockFile) return;
-			let args;
-			if (client === "npm") args = ["ci"];
-			else if (client === "yarn") args = ["install", "--immutable"];
-			else if (client === "bun") args = ["install", "--frozen-lockfile"];
-			else args = ["install", "--frozen-lockfile"];
-			const result = await x(client, args, { nodeOptions: { cwd: this.cwd } });
-			if (result.exitCode !== 0) throw execFailure("Failed to update lockfile.", result);
-		} }
-	};
-}
-function depsPolicy(context, getBumpDepType) {
-	const { graph } = context;
-	function needsUpdate(spec, target) {
-		if (spec.linked && spec.protocol === "workspace") switch (spec.range) {
-			case "":
-			case "*": return true;
-			case "^":
-			case "~": return !semver.satisfies(target, `${spec.range}${spec.linked.version}`);
-		}
-		if (spec.linked && spec.protocol === "file") return true;
-		if (spec.protocol === "file" || !semver.validRange(spec.range)) return false;
-		return !semver.satisfies(target, spec.range);
-	}
-	return {
-		id: "npm:deps",
-		onUpdate({ pkg, packageDraft: plan }) {
-			if (!(pkg instanceof NpmPackage)) return;
-			const group = graph.getPackageGroup(pkg.id);
-			for (const dependent of graph.getPackages()) {
-				if (!(dependent instanceof NpmPackage)) continue;
-				for (const field of DEP_FIELDS) {
-					const dependencies = dependent.manifest[field];
-					if (!dependencies) continue;
-					for (const [k, v] of Object.entries(dependencies)) {
-						const spec = parseDependencySpec(context, dependent, k, v);
-						if (!spec || spec.linked !== pkg) continue;
-						if (group?.options.syncBump && graph.getPackageGroup(dependent.id) === group) continue;
-						if (!needsUpdate(spec, plan.bumpVersion(pkg))) continue;
-						const bumpType = getBumpDepType({
-							kind: field,
-							spec,
-							name: k
-						});
-						if (bumpType === false) continue;
-						this.bumpPackage(dependent, {
-							type: bumpType,
-							reason: `update dependency "${k}"`
-						});
-					}
-				}
-			}
-		}
-	};
-}
-async function publish(client, pkg, distTag) {
-	if (client === "bun") {
-		for (const script of [
-			"prepublishOnly",
-			"prepack",
-			"prepare"
-		]) {
-			if (!pkg.manifest.scripts?.[script]) continue;
-			const result = await x("bun", ["run", script], { nodeOptions: { cwd: pkg.path } });
-			if (result.exitCode === 0) continue;
-			return {
-				type: "failed",
-				error: execFailure(`Failed to run ${script} script for ${pkg.name}@${pkg.version}.`, result).message
-			};
-		}
-		const tarballPath = path.resolve(pkg.path, "pkg.tgz");
-		const packResult = await x("bun", [
-			"pm",
-			"pack",
-			"--filename",
-			tarballPath
-		], { nodeOptions: { cwd: pkg.path } });
-		if (packResult.exitCode !== 0) return {
-			type: "failed",
-			error: execFailure(`Failed to pack ${pkg.name}@${pkg.version}.`, packResult).message
-		};
-		const publishArgs = ["publish", tarballPath];
-		if (distTag) publishArgs.push("--tag", distTag);
-		const publishResult = await x("npm", publishArgs, { nodeOptions: { cwd: pkg.path } });
-		if (publishResult.exitCode !== 0) return {
-			type: "failed",
-			error: execFailure(`Failed to publish ${pkg.name}@${pkg.version}${distTag ? ` with dist-tag "${distTag}"` : ""}.`, publishResult).message
-		};
-		return { type: "published" };
-	}
-	let command;
-	const args = ["publish"];
-	if (distTag) args.push("--tag", distTag);
-	if (client === "pnpm") {
-		command = "pnpm";
-		args.push("--no-git-checks");
-	} else if (client === "yarn") command = "yarn";
-	else command = "npm";
-	const result = await x(command, args, { nodeOptions: { cwd: pkg.path } });
-	if (result.exitCode !== 0) return {
-		type: "failed",
-		error: execFailure(`Failed to publish ${pkg.name}@${pkg.version}${distTag ? ` with dist-tag "${distTag}"` : ""}.`, result).message
-	};
-	return { type: "published" };
-}
-async function isPackagePublished(pkg) {
-	const registry = pkg.manifest.publishConfig?.registry ?? "https://registry.npmjs.org";
-	const base = registry.replace(/\/$/, "");
-	const response = await fetch(`${base}/${pkg.name}/${pkg.version}`, { headers: { Accept: "application/json" } });
-	if (response.status === 404) return false;
-	if (!response.ok) throw new Error(`Unable to validate ${pkg.name}@${pkg.version} against the npm registry${registry ? ` "${registry}"` : ""}.`);
-	return true;
-}
-async function discoverNpmPackages(cwd, add) {
-	let patterns;
-	const rootManifest = await readManifest(cwd).catch(() => void 0);
-	const pnpmPatterns = await readFile(path.join(cwd, "pnpm-workspace.yaml"), "utf8").then((content) => pnpmWorkspaceSchema.parse(load(content) ?? {})).catch((error) => {
-		if (isNodeError(error) && error.code === "ENOENT") return void 0;
-		throw error;
-	});
-	if (pnpmPatterns) patterns = pnpmPatterns.packages ?? [];
-	else patterns = rootManifest?.workspaces ?? [];
-	const candidatePaths = await expandWorkspacePatterns(cwd, patterns);
-	const manifests = await Promise.all(candidatePaths.map((path) => readManifest(path).then((manifest) => ({
-		path,
-		manifest
-	})).catch(() => void 0)));
-	if (rootManifest?.version) add(new NpmPackage(cwd, rootManifest));
-	for (const entry of manifests) {
-		if (!entry?.manifest.version) continue;
-		add(new NpmPackage(entry.path, entry.manifest));
-	}
-}
-async function expandWorkspacePatterns(cwd, patterns) {
-	if (patterns.length === 0) return [];
-	return (await glob(patterns, {
-		absolute: true,
-		cwd,
-		ignore: ["**/node_modules/**", "**/dist/**"],
-		onlyDirectories: true,
-		onlyFiles: false
-	})).map((item) => {
-		return item.endsWith(path.sep) ? item.slice(0, -1) : item;
-	});
-}
-async function readManifest(packagePath) {
-	const content = await readFile(path.join(packagePath, "package.json"), "utf8");
-	const parsed = JSON.parse(content);
-	packageManifestSchema.parse(parsed);
-	return parsed;
-}
-//#endregion
+import { n as npm, t as NpmPackage } from "../npm-DqGyAsdo.js";
 export { NpmPackage, npm };

package/dist/{semver-C4vJ4SK8.js → semver-EKJ8yK5U.js}

@@ -4,7 +4,10 @@ function formatNpmDistTag(distTag) {
 	return distTag && distTag !== "latest" ? ` (${distTag})` : "";
 }
 function formatPackageVersion(name, version, distTag) {
-	return `${name}@${version}${formatNpmDistTag(distTag)}`;
+	let out = name;
+	if (version) out += `@${version}`;
+	out += formatNpmDistTag(distTag);
+	return out;
 }
 const WEIGHTS = {
 	major: 3,
@@ -33,7 +36,8 @@ function bumpVersion(version, type, prerelease) {
 	const parsed = parse(version);
 	if (!parsed) next = null;
 	else if (prerelease) {
-		if (parsed.prerelease[0] === prerelease && type) next = inc(parsed, "prerelease", prerelease);
+		if (parsed.prerelease[0] === prerelease) next = type ? inc(parsed, "prerelease", prerelease) : version;
+		else if (parsed.prerelease[0]) next = inc(parsed, "prerelease", prerelease);
 		else if (type) next = inc(parsed, PRE[type], prerelease);
 	} else if (type) next = inc(parsed, type);
 	else if (parsed.prerelease.length > 0) next = inc(parsed, "release");

package/dist/{types-DEaKjB3O.d.ts → types-BbDtPn8I.d.ts}

@@ -1,4 +1,4 @@
-import z, { z as z$1 } from "zod";
+import z from "zod";
 import { AgentName } from "package-manager-detector";
 
 //#region src/utils/semver.d.ts
@@ -42,8 +42,8 @@ interface PackageDraft {
   npm?: {
     /** npm dist-tag used when publishing. */distTag?: string;
   };
-  /** get the bumped version of a package */
-  bumpVersion: (pkg: WorkspacePackage) => string;
+  /** get the bumped version of a package, return `undefined` if the package doesn't have a `version` field */
+  bumpVersion: (pkg: WorkspacePackage) => string | undefined;
 }
 /** a draft describes all operations to perform before the actual publishing, such as version bumps. */
 declare class Draft {
@@ -67,6 +67,7 @@ declare class Draft {
   dispatchPackage(pkg: WorkspacePackage, dispatch: (draft: PackageDraft) => void, onUpdate?: (draft: PackageDraft) => void): PackageDraft;
   getOrInitPackage(pkg: WorkspacePackage): PackageDraft;
   hasPending(): boolean;
+  /** get all changelogs, note that this includes replay-only changelogs, as long as they are in the `.tegami` folder. */
   getChangelogs(): ChangelogEntry[];
   getChangelog(id: string): ChangelogEntry | undefined;
   addChangelog(entry: ChangelogEntry): void;
@@ -96,9 +97,10 @@ interface DraftPolicy {
 /** Package discovered in the workspace. */
 declare abstract class WorkspacePackage {
   abstract readonly name: string;
+  /** absolute path */
   abstract readonly path: string;
   abstract readonly manager: string;
-  abstract readonly version: string;
+  abstract readonly version: string | undefined;
   get id(): string;
   private opts;
   /** note: this will only be available after package graph is resolved */
@@ -158,141 +160,27 @@ interface TegamiContext {
   };
 }
 //#endregion
-//#region src/changelog/generate.d.ts
-interface GenerateFromCommitsOptions {
-  /** Start revision. Defaults to the latest reachable git tag, or all history if none exists. */
-  from?: string;
-  /** End revision. Defaults to HEAD. */
-  to?: string;
-}
-interface CommitChangelog {
-  filename: string;
-  content: string;
-  packages: Record<string, BumpType | ChangelogPackageConfig>;
-  changes: CommitChange[];
-}
-interface CommitChange {
-  hash: string;
-  subject: string;
-  body: string;
-  packages: string[];
-  type: BumpType;
-  title: string;
-}
-//#endregion
-//#region src/plans/publish.d.ts
-interface PublishPlan {
-  options: PublishOptions;
-  /** id -> entry */
-  changelogs: Map<string, ChangelogEntry>;
-  /** id -> package data. The package id will always exist in package graph, stale items will be pruned at init-time */
-  packages: Map<string, PackagePublishPlan>;
-}
-interface PackagePublishPlan {
-  changelogs: ChangelogEntry[];
-  /** whether this package was version-bumped when the lock was written */
-  updated: boolean;
-  /** generated by Git plugin */
-  git?: {
-    /** the associated Git tag of package */tag: string;
-  };
-  /** generated by npm plugin */
-  npm?: {
-    /** dist tag to use if published */distTag?: string;
-  };
-  /** publish result, generated for all packages in publish plan after publishing */
-  publishResult?: PackagePublishResult;
-  /** preflight result, generated for all packages in publish plan after preflights */
-  preflight?: PublishPreflight;
-}
-interface PublishOptions {
-  /** Validate the publish plan without publishing packages, creating tags, or running release plugins. */
-  dryRun?: boolean;
-}
-type PackagePublishResult = {
-  type: "published" | "skipped";
-} | {
-  type: "failed";
-  error: string;
-};
-//#endregion
-//#region src/plans/lock.d.ts
-/**
- * the data structure of `publish-lock.yaml` file.
- */
-declare class PublishLock {
-  /** namespace -> data array */
-  private readonly data;
-  constructor(/** namespace -> data array */
-
-  data?: Map<string, unknown[]>);
-  /** write data to namespace, note that the `data` must be serializable in yaml */
-  write(namespace: string, data: unknown): void;
-  read(namespace: string): unknown | undefined;
-  size(namespace: string): number;
-  serialize(): string;
-}
-//#endregion
-//#region src/index.d.ts
-interface GenerateChangelogOptions extends GenerateFromCommitsOptions {
-  /**
-   * Write changelog files to disk.
-   *
-   * @default true
-   */
-  write?: boolean;
-}
-interface Tegami {
-  /** Create pending changelog files from git commit history. */
-  generateChangelog(options?: GenerateChangelogOptions): Promise<CommitChangelog[]>;
-  /** Build a draft from pending changelog files. */
-  draft(): Promise<Draft>;
-  /** Publish packages from the publish lock. */
-  publish(options?: PublishOptions): Promise<PublishPlan | "skipped">;
-  /**
-   * Check publish status.
-   *
-   * Prefer `publish()` over this if you are publishing packages, it will also check the publish status.
-   */
-  publishStatus(): Promise<"pending" | "success" | "idle">;
-  /** Remove the publish lock file after publishing has finished successfully. */
-  cleanup(): Promise<{
-    state: "removed";
-  } | {
-    state: "skipped";
-    reason: "no-plan" | "pending";
-  }>;
-  /** Internal APIs, do not use it unless you know what you are doing */
-  _internal: {
-    context(): Promise<TegamiContext>;
-    graph(): Promise<PackageGraph>;
-    options: TegamiOptions;
-  };
-}
-/** Create a Tegami project handle. */
-declare function tegami<const Groups extends string = string>(options?: TegamiOptions<Groups>): Tegami;
-//#endregion
-//#region src/schemas.d.ts
-declare const packageManifestSchema: z$1.ZodObject<{
-  name: z$1.ZodString;
-  version: z$1.ZodOptional<z$1.ZodString>;
-  private: z$1.ZodOptional<z$1.ZodBoolean>;
-  publishConfig: z$1.ZodOptional<z$1.ZodObject<{
-    access: z$1.ZodOptional<z$1.ZodEnum<{
+//#region src/providers/npm/schema.d.ts
+declare const packageManifestSchema: z.ZodObject<{
+  name: z.ZodString;
+  version: z.ZodOptional<z.ZodString>;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publishConfig: z.ZodOptional<z.ZodObject<{
+    access: z.ZodOptional<z.ZodEnum<{
       public: "public";
       restricted: "restricted";
     }>>;
-    registry: z$1.ZodOptional<z$1.ZodString>;
-    tag: z$1.ZodOptional<z$1.ZodString>;
-  }, z$1.core.$loose>>;
-  scripts: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  workspaces: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
-  dependencies: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  devDependencies: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  peerDependencies: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  optionalDependencies: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-}, z$1.core.$loose>;
-type PackageManifest = z$1.infer<typeof packageManifestSchema>;
+    registry: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  scripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  workspaces: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  optionalDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$loose>;
+type PackageManifest = z.infer<typeof packageManifestSchema>;
 //#endregion
 //#region src/providers/npm.d.ts
 declare const DEP_FIELDS$1: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
@@ -302,9 +190,10 @@ declare class NpmPackage extends WorkspacePackage {
   readonly manager = "npm";
   constructor(path: string, manifest: PackageManifest);
   get name(): string;
-  get version(): string;
+  get version(): string | undefined;
   write(): Promise<void>;
   initDraft(): PackageDraft;
+  configureDraft(draft: PackageDraft, group?: PackageGroup): void;
 }
 type DependencySpec = {
   protocol: "npm";
@@ -331,6 +220,7 @@ interface NpmPluginOptions {
    * Decide how to bump the dependents of a bumped package.
    */
   bumpDep?: (opts: {
+    dependent: NpmPackage;
     kind: (typeof DEP_FIELDS$1)[number];
     name: string;
     spec: DependencySpec;
@@ -369,7 +259,7 @@ declare class CargoPackage extends WorkspacePackage {
   readonly manager = "cargo";
   constructor(path: string, manifest: TomlTable, content: string, workspaceManifest?: TomlTable | undefined);
   get name(): string;
-  get version(): string;
+  get version(): string | undefined;
   setVersion(version: string): void;
   write(): Promise<void>;
   patch(path: string, value: unknown): void;
@@ -383,7 +273,11 @@ interface CargoPluginOptions {
    * @default true
    */
   updateLockFile?: boolean;
+  /**
+   * Decide how to bump the dependents of a bumped package.
+   */
   bumpDep?: (opts: {
+    dependent: CargoPackage;
     kind: (typeof DEP_FIELDS)[number];
     name: string;
     version: string;
@@ -394,6 +288,59 @@ declare function cargo({
   bumpDep: getBumpDepType
 }?: CargoPluginOptions): TegamiPlugin;
 //#endregion
+//#region src/plans/publish.d.ts
+interface PublishPlan {
+  options: PublishOptions;
+  /** id -> entry */
+  changelogs: Map<string, ChangelogEntry>;
+  /** id -> package data. The package id will always exist in package graph, stale items will be pruned at init-time */
+  packages: Map<string, PackagePublishPlan>;
+}
+interface PackagePublishPlan {
+  changelogs: ChangelogEntry[];
+  /** whether this package was version-bumped when the lock was written */
+  updated: boolean;
+  /** generated by Git plugin */
+  git?: {
+    /** the associated Git tag of package */tag?: string;
+  };
+  /** generated by npm plugin */
+  npm?: {
+    /** dist tag to use if published */distTag?: string;
+  };
+  /** publish result, generated for all packages in publish plan after publishing */
+  publishResult?: PackagePublishResult;
+  /** preflight result, generated for all packages in publish plan after preflights */
+  preflight?: PublishPreflight;
+}
+interface PublishOptions {
+  /** Validate the publish plan without publishing packages, creating tags, or running release plugins. */
+  dryRun?: boolean;
+}
+type PackagePublishResult = {
+  type: "published" | "skipped";
+} | {
+  type: "failed";
+  error: string;
+};
+//#endregion
+//#region src/plans/lock.d.ts
+/**
+ * the data structure of `publish-lock.yaml` file.
+ */
+declare class PublishLock {
+  /** namespace -> data array */
+  private readonly data;
+  constructor(/** namespace -> data array */
+
+  data?: Map<string, unknown[]>);
+  /** write data to namespace, note that the `data` must be serializable in yaml */
+  write(namespace: string, data: unknown): void;
+  read(namespace: string): unknown | undefined;
+  size(namespace: string): number;
+  serialize(): string;
+}
+//#endregion
 //#region src/types.d.ts
 /** Generates changelog content for a package release. */
 interface LogGenerator {
@@ -412,8 +359,8 @@ interface TegamiOptions<Groups extends string = string> {
   lockPath?: string;
   /** Changelog generator used when applying a draft. */
   generator?: LogGenerator;
-  /** Per-package release and publish options keyed by package name. */
-  packages?: Record<string, PackageOptions<NoInfer<Groups>>>;
+  /** Per-package options keyed by package name or a function. */
+  packages?: Record<string, PackageOptions<NoInfer<Groups>>> | ((pkg: WorkspacePackage) => PackageOptions<NoInfer<Groups>> | undefined);
   plugins?: TegamiPluginOption[];
   groups?: Record<Groups, GroupOptions>;
   /** Package names, ids, or regex patterns to exclude from the dependency graph. */
@@ -455,7 +402,7 @@ type TegamiPluginOption = TegamiPlugin | TegamiPluginOption[];
 interface TegamiPlugin {
   name: string;
   enforce?: "pre" | "default" | "post";
-  /** when Tegami initializes */
+  /** When Tegami initializes */
   init?(this: TegamiContext): Awaitable<void>;
   /** Resolve workspace packages and dependency metadata into the shared graph. */
   resolve?(this: TegamiContext): Awaitable<void>;
@@ -495,7 +442,7 @@ interface TegamiPlugin {
   willPublish?(this: TegamiContext, opts: {
     pkg: WorkspacePackage;
   }): Awaitable<false | void | undefined>;
-  /** Called after a package is published, skipped, or failed. */
+  /** Called after a package is published successfully, or failed. */
   afterPublish?(this: TegamiContext, opts: {
     pkg: WorkspacePackage;
     plan: PublishPlan;
@@ -523,4 +470,4 @@ interface PublishPreflight {
   wait?: string[];
 }
 //#endregion
-export { PackageDraft as A, CommitChangelog as C, WorkspacePackage as D, PackageGroup as E, Draft as O, PublishPlan as S, PackageGraph as T, tegami as _, PublishPreflight as a, PackagePublishResult as b, TegamiPluginOption as c, cargo as d, NpmPackage as f, Tegami as g, GenerateChangelogOptions as h, PackageOptions as i, DraftPolicy as k, CargoPackage as l, npm as m, GroupOptions as n, TegamiOptions as o, NpmPluginOptions as p, LogGenerator as r, TegamiPlugin as s, Awaitable as t, CargoPluginOptions as u, PublishLock as v, TegamiContext as w, PublishOptions as x, PackagePublishPlan as y };
+export { WorkspacePackage as C, ChangelogPackageConfig as D, PackageDraft as E, BumpType as O, PackageGroup as S, DraftPolicy as T, NpmPackage as _, PublishPreflight as a, TegamiContext as b, TegamiPluginOption as c, PackagePublishResult as d, PublishOptions as f, cargo as g, CargoPluginOptions as h, PackageOptions as i, PublishLock as l, CargoPackage as m, GroupOptions as n, TegamiOptions as o, PublishPlan as p, LogGenerator as r, TegamiPlugin as s, Awaitable as t, PackagePublishPlan as u, NpmPluginOptions as v, Draft as w, PackageGraph as x, npm as y };