@dbx-tools/cli 0.1.103

package/README.md

@@ -0,0 +1,88 @@
+# @dbx-tools/dbxtools
+
+Scaffold, formatting, codegen, verification, build, and release helpers for Bun +
+workspaces monorepos. It wraps the shared `tsdown` config for building and a
+Bun-based publish flow; `dbxtools` keeps only the workspace automation that is
+orthogonal to writing package code.
+
+## Installation
+
+```bash
+bun add -d @dbx-tools/dbxtools
+```
+
+Then point your root `package.json` scripts at the `dbxtools` bin for the helper
+commands you want:
+
+```jsonc
+{
+  "scripts": {
+    "format": "dbxtools format",
+    "build": "dbxtools build",
+    "codegen": "dbxtools codegen",
+    "verify": "dbxtools verify",
+    "create": "dbxtools create",
+    "release": "dbxtools release",
+    "tag": "dbxtools tag",
+  },
+}
+```
+
+## Commands
+
+| Command                                     | What it does                                                                                         |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `dbxtools format`                             | `syncpack format`, regroup lifecycle hooks, then `prettier --write`.                                 |
+| `dbxtools build`                              | Compile every publishable package with the shared `tsdown` config.                                   |
+| `dbxtools codegen`                            | Regenerate each package's `generated/` zod tree from the `.d.ts` inputs its `package.json` declares. |
+| `dbxtools verify`                             | Fail on imports of sibling packages not declared as dependencies.                                    |
+| `dbxtools create [--plugin\|--shared] <slug>` | Scaffold a new package under `packages/<slug>/`.                                                     |
+| `dbxtools release [--dry-run]`                | Build, then publish each package with a stamped (complete) manifest.                                 |
+| `dbxtools tag [patch\|minor\|major]`          | Version bump, commit, tag, push, and create a GitHub Release. `--notes-since v0.1.75` widens the notes baseline; default is the previous tag. `--no-ai-notes` skips Codex release notes. |
+| `dbxtools agent [prompt]`                     | Run `ucode codex exec` (`-t` / `--timeout` seconds). Prompt via args or stdin. Requires `ucode codex --version`. |
+
+Typecheck stays a plain `tsc` call:
+
+```bash
+tsc --noEmit -p tsconfig.json
+```
+
+## Configuration
+
+Configuration is optional. Everything is auto-derived from the workspace; the
+only knobs live under a `dbxtools` key in the root `package.json`:
+
+```jsonc
+{
+  "dbxtools": {
+    "scope": "@acme", // npm scope used by `create` (default: most common scope in the workspace)
+    "repo": "acme/widgets", // owner/name for release links (default: the `origin` git remote)
+  },
+}
+```
+
+Each package's optional `codegen.inputs` field is read by convention.
+
+## Library API
+
+The same commands are exported as functions for projects that want to compose
+their own automation:
+
+```ts
+import { build, codegen, create, release, tag, verify } from "@dbx-tools/dbxtools";
+
+await build();
+await codegen();
+await verify();
+await create({ slug: "example" });
+await release({ dryRun: true });
+await tag({ bump: "patch", publish: false });
+```
+
+Also exported: `format`, plus the workspace helpers
+(`discoverPackages`, `discoverPackageJsons`, `writeJson`, `getProject`, `sh`,
+`git`, ...).
+
+## License
+
+Apache-2.0

package/dist/bin/dbxtools.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/bin/dbxtools.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+import { C as codegen, S as build, b as resolveAgentPrompt, d as release, f as format, g as agent, l as notesSinceRequested, n as forwardedUpdateArgs, p as create, s as update, t as verify, u as tag } from "../verify-CTCK1U-t.js";
+import { Command, InvalidArgumentError } from "commander";
+
+//#region packages/cli/bin/dbxtools.ts
+const program = new Command().name("dbxtools").description("Workspace build, scaffold, and release toolkit for Bun monorepos.");
+program.command("format").description("syncpack format, regroup lifecycle hooks, then prettier --write.").action(format);
+program.command("build").description("Compile every publishable package with the shared tsdown config.").action(build);
+program.command("release").description("Build, then publish each package with a stamped (complete) manifest.").option("-n, --dry-run", "rehearse with `bun publish --dry-run`", false).action(async (opts) => {
+	await release({ dryRun: opts.dryRun });
+});
+program.command("codegen").description("Regenerate each package's `generated/` zod tree from its inputs.").action(codegen);
+program.command("verify").description("Fail on imports of sibling packages not declared as dependencies.").action(verify);
+program.command("update").description("Pin root catalog entries to latest stable versions, then bun update at the repo root.").allowUnknownOption().action(async () => {
+	await update(forwardedUpdateArgs());
+});
+program.command("create").description("Scaffold a new workspace package under packages/<slug>/.").argument("<slug>", "kebab-case slug (lowercase, starts with a letter)", (value) => {
+	if (!/^[a-z][a-z0-9-]*$/.test(value)) throw new InvalidArgumentError(`invalid slug "${value}"`);
+	return value;
+}).option("--plugin", "scaffold an AppKit plugin package").option("--shared", "scaffold a browser-safe shared package").action(async (slug, opts) => {
+	await create({
+		slug,
+		plugin: opts.plugin,
+		shared: opts.shared
+	});
+});
+program.command("agent").description("Run ucode codex exec with assistant output.").argument("[prompt...]", "prompt text (or pipe via stdin when omitted)").option("-t, --timeout <seconds>", "wall-clock budget in seconds (default 300)", (value) => {
+	const seconds = Number(value);
+	if (!Number.isFinite(seconds) || seconds <= 0) throw new InvalidArgumentError("timeout must be a positive number");
+	return Math.round(seconds * 1e3);
+}).action(async (promptParts, opts) => {
+	const code = await agent({
+		prompt: await resolveAgentPrompt(promptParts),
+		timeoutMs: opts.timeout
+	});
+	if (code !== 0) process.exit(code);
+});
+program.command("tag").description("Bump every workspace, commit, tag HEAD, and push to origin.").argument("[bump]", "version bump (patch | minor | major)", (value) => {
+	if (value !== "patch" && value !== "minor" && value !== "major") throw new InvalidArgumentError("expected patch, minor, or major");
+	return value;
+}, "patch").option("--no-publish", "skip publishing the tagged versions to the local registry").option("-n, --dry-run", "print the plan and release-notes preview; write nothing, push nothing", false).option("--notes-since <tag>", "widen release-notes baseline to this tag (e.g. v0.1.75); default is the previous tag on HEAD").option("--no-ai-notes", "skip ucode codex; use commit-grouped notes only").action(async (bump, opts) => {
+	await tag({
+		bump,
+		dryRun: opts.dryRun,
+		publish: opts.publish,
+		aiNotes: opts.aiNotes,
+		...notesSinceRequested(opts.notesSince) ? { notesSince: opts.notesSince } : {}
+	});
+});
+await program.parseAsync(process.argv);
+
+//#endregion
+export {  };

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+import { FileSystemProject, Workspace } from "pacwich";
+
+//#region packages/cli/src/build.d.ts
+/** Compile every publishable package with the shared tsdown config. */
+declare function build(): Promise<void>;
+//#endregion
+//#region packages/cli/src/agent.d.ts
+/**
+ * Run Codex headlessly via `ucode codex exec` for `dbxtools agent` and
+ * release tooling that drafts notes programmatically.
+ */
+/** Default wall-clock budget for a Codex invocation. */
+declare const AGENT_DEFAULT_TIMEOUT_MS = 300000;
+/** Options for {@link runAgent}. */
+interface AgentOptions {
+  /** Wall-clock budget in milliseconds. */
+  timeoutMs?: number;
+  /** Working directory for the agent (defaults to `process.cwd()`). */
+  cwd?: string;
+  /**
+   * When `true` (default), capture stdout via `sh({ quiet: true })` for
+   * programmatic callers. When `false`, inherit stdio like
+   * `ucode codex exec …` in a shell.
+   */
+  capture?: boolean;
+  /**
+   * When `true` (default) and `capture` is enabled, write the parsed
+   * assistant text to stdout. Set `false` when the caller will log the
+   * result itself (e.g. release-notes drafting).
+   */
+  echo?: boolean;
+}
+/** Outcome of {@link runAgent}. */
+interface AgentResult {
+  /** Trimmed assistant answer. */
+  text: string;
+  /** Subprocess exit code. */
+  exitCode: number;
+  /** Trimmed stderr. */
+  stderr: string;
+}
+/** Options for {@link agent}. */
+interface AgentCommandOptions {
+  /** Prompt passed to `ucode codex exec`. */
+  prompt: string;
+  /** Wall-clock budget in milliseconds. */
+  timeoutMs?: number;
+}
+/** Whether `ucode codex --version` reports a usable Codex CLI. */
+declare function agentAvailable(): Promise<boolean>;
+/** Whether an exit code looks like the process was killed on a timeout. */
+declare function agentTimedOut(exitCode: number): boolean;
+/** Pull assistant prose out of `ucode codex exec` stdout. */
+declare function parseCodexStdout(stdout: string): string;
+/**
+ * Run `ucode codex exec` and return captured output. Throws when Codex
+ * is absent or the wall-clock budget is exceeded. On a non-zero exit
+ * the result is still returned so callers can use partial text.
+ */
+declare function runAgent(prompt: string, opts?: AgentOptions): Promise<AgentResult>;
+/**
+ * `dbxtools agent` entry: run Codex and return a process exit code (0 on
+ * success, 1 on failure or timeout).
+ */
+declare function agent(opts: AgentCommandOptions): Promise<number>;
+/** Join argv prompt parts, or read stdin when non-interactive and args are empty. */
+declare function resolveAgentPrompt(promptParts: string[]): Promise<string>;
+//#endregion
+//#region packages/cli/src/codegen.d.ts
+/** Regenerate the `generated/` tree for every package declaring a `codegen` field. */
+declare function codegen(): Promise<void>;
+//#endregion
+//#region packages/cli/src/config.d.ts
+/** Resolved toolkit configuration for the current repo. */
+interface DbxtoolsConfig {
+  /** npm scope (e.g. `@acme`) used when scaffolding new packages. */
+  scope: string;
+  /** `owner/name` slug used for release links, or null when undiscoverable. */
+  repo: string | null;
+  /**
+   * Name of the shared-helpers package `create` wires as a dependency
+   * into new plugin / standard packages (when it exists in the
+   * workspace). Defaults to `<scope>/shared`, or null when no scope
+   * resolves.
+   */
+  sharedPackage: string | null;
+}
+/**
+ * Resolve toolkit config for the current repo, memoized for the
+ * process. Overrides under the root `package.json` `dbxtools` key win
+ * over the auto-derived defaults.
+ */
+declare const getDbxtoolsConfig: () => Promise<DbxtoolsConfig>;
+//#endregion
+//#region packages/cli/src/create.d.ts
+/** Options for {@link create}. */
+interface CreateOptions {
+  /** kebab-case slug (lowercase, starts with a letter). */
+  slug: string;
+  /** Scaffold an AppKit plugin package. */
+  plugin?: boolean;
+  /** Scaffold a browser-safe shared package. */
+  shared?: boolean;
+}
+/** Scaffold a new workspace package under `packages/<slug>/`. */
+declare function create(options: CreateOptions): Promise<void>;
+//#endregion
+//#region packages/cli/src/format.d.ts
+/** syncpack + lifecycle-hook regroup + prettier across the workspace. */
+declare function format(): Promise<void>;
+//#endregion
+//#region packages/cli/src/shell.d.ts
+interface ShellResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+interface ShellOptions {
+  /** Return the result on non-zero exit instead of throwing. */
+  nothrow?: boolean;
+  /** Working directory for the command. */
+  cwd?: string;
+  /** String piped to the command's stdin. */
+  input?: string;
+  /** Suppress the live echo. Output is still captured on the result. */
+  quiet?: boolean;
+}
+/**
+ * Run a command, streaming live unless `quiet`. Returns trimmed captured
+ * output regardless. Throws on non-zero unless `nothrow`.
+ */
+declare function sh(args: string[], opts?: ShellOptions): Promise<ShellResult>;
+/** `bun x <args>` for one-off CLI tools (knip, syncpack, prettier, ...). */
+declare function bunx(args: string[], opts?: ShellOptions): Promise<ShellResult>;
+//#endregion
+//#region packages/cli/src/git.d.ts
+/**
+ * Run `git <args>`, returning trimmed output. Quiet by default since git is
+ * used mostly for its stdout (rev-parse, log, diff, ...); pass `quiet: false`
+ * to stream a mutating op live. Throws on non-zero unless `nothrow`.
+ */
+declare function git(args: string[], opts?: {
+  nothrow?: boolean;
+  quiet?: boolean;
+  cwd?: string;
+}): Promise<ShellResult>;
+//#endregion
+//#region packages/cli/src/package.d.ts
+/** Minimal package.json shape the commands care about. */
+interface PackageJson {
+  name?: string;
+  version?: string;
+  private?: boolean;
+  workspaces?: string[];
+  [key: string]: unknown;
+}
+/** A workspace package: its parsed manifest, location, and dependency edges. */
+declare class WorkspacePackage {
+  readonly meta: PackageJson;
+  readonly dir: string;
+  readonly slug: string;
+  readonly jsonPath: string;
+  private constructor();
+  /** Build from a pacwich {@link Workspace}, reading its manifest. */
+  static fromWorkspace(ws: Workspace): Promise<WorkspacePackage>;
+}
+/** Resolve `path` against the repo root. */
+declare function toAbsolute(path: string): string;
+/** Repo-relative form of `path`, or absolute when it sits outside the root. */
+declare function toRelative(path: string): string;
+/** Yield every workspace `package.json` path (`includeRoot` prepends the root manifest). */
+declare function discoverPackageJsons(includeRoot?: boolean): AsyncIterableIterator<string>;
+/** Workspace packages passing `filter` (default: non-private), sorted by slug. */
+declare function discoverPackages(filter?: (pkg: WorkspacePackage) => boolean): Promise<WorkspacePackage[]>;
+/** Write `value` as JSON, preserving the file's trailing newline to avoid format churn. */
+declare function writeJson(path: string, value: unknown): Promise<void>;
+//#endregion
+//#region packages/cli/src/project.d.ts
+declare const getProject: () => Promise<FileSystemProject>;
+//#endregion
+//#region packages/cli/src/release.d.ts
+/** Options for {@link release}. */
+interface ReleaseOptions {
+  /** Rehearse with `bun publish --dry-run` instead of publishing. */
+  dryRun?: boolean;
+}
+/**
+ * Build every publishable package, then publish each with a stamped
+ * (complete) `package.json`, restoring the slim source manifest after
+ * each publish whether it succeeds or fails.
+ */
+declare function release(opts?: ReleaseOptions): Promise<void>;
+//#endregion
+//#region packages/cli/src/script.d.ts
+/** Log `message` and exit non-zero. */
+declare function fail(message: string): never;
+/** Narrow an unknown thrown value to its message string. */
+declare function errorMessage(err: unknown): string;
+/** Split text on newlines, trimming each line and dropping blanks. */
+declare function nonEmptyLines(text: string): string[];
+//#endregion
+//#region packages/cli/src/tag.d.ts
+type Bump = "major" | "minor" | "patch";
+/** Options for {@link tag}. */
+interface TagOptions {
+  /** Version bump (defaults to `patch`). */
+  bump?: Bump;
+  /** Print everything, write nothing. */
+  dryRun?: boolean;
+  /** Publish the tagged versions to the local registry (default true). */
+  publish?: boolean;
+  /**
+   * When set, widen the release-notes baseline to this tag instead of
+   * the latest tag on `HEAD` (e.g. `v0.1.75` when several recent tags
+   * failed to publish). Omit to use the previous tag only.
+   */
+  notesSince?: string;
+  /** When false, skip Codex and use commit-grouped notes only. */
+  aiNotes?: boolean;
+}
+/**
+ * Version-bump every publishable workspace, commit, tag, push, create
+ * the GitHub Release (with generated notes), and publish to the local
+ * registry. See the file header for the full local-state policy.
+ */
+declare function tag(opts?: TagOptions): Promise<void>;
+//#endregion
+//#region packages/cli/src/update.d.ts
+/** True when `version` is a release with no prerelease segment. */
+declare function isStableVersion(version: string): boolean;
+/** Highest stable version in `versions` that satisfies `range`. */
+declare function latestStableInRange(versions: string[], range: string): string | null;
+/** Rewrite a single range (or `latest`) to a caret pin on the latest stable match. */
+declare function stableCaretRange(versions: string[], range: string): string;
+/** Refresh every root `catalog` entry to the latest stable release in-range. */
+declare function updateCatalog(): Promise<boolean>;
+/** Run `bun update` with `forwardArgs` at the repo root. */
+declare function runBunUpdate(forwardArgs: string[]): Promise<void>;
+/** Refresh catalog pins, then `bun update` at the repo root. */
+declare function update(forwardArgs?: string[]): Promise<void>;
+/** Args after the `update` subcommand in `process.argv`. */
+declare function forwardedUpdateArgs(argv?: string[]): string[];
+//#endregion
+//#region packages/cli/src/verify.d.ts
+/** Fail when any workspace imports a sibling it doesn't declare as a dependency. */
+declare function verify(): Promise<void>;
+//#endregion
+export { AGENT_DEFAULT_TIMEOUT_MS, type AgentCommandOptions, type AgentOptions, type AgentResult, type Bump, type CreateOptions, type DbxtoolsConfig, type PackageJson, type ReleaseOptions, type ShellResult, type TagOptions, WorkspacePackage, agent, agentAvailable, agentTimedOut, build, bunx, codegen, create, discoverPackageJsons, discoverPackages, errorMessage, fail, format, forwardedUpdateArgs, getDbxtoolsConfig, getProject, git, isStableVersion, latestStableInRange, nonEmptyLines, parseCodexStdout, release, resolveAgentPrompt, runAgent, runBunUpdate, sh, stableCaretRange, tag, toAbsolute, toRelative, update, updateCatalog, verify, writeJson };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { A as git, C as codegen, D as toAbsolute, E as discoverPackages, F as nonEmptyLines, I as getProject, M as sh, N as errorMessage, O as toRelative, P as fail, S as build, T as discoverPackageJsons, _ as agentAvailable, a as runBunUpdate, b as resolveAgentPrompt, c as updateCatalog, d as release, f as format, g as agent, h as AGENT_DEFAULT_TIMEOUT_MS, i as latestStableInRange, j as bunx, k as writeJson, m as getDbxtoolsConfig, n as forwardedUpdateArgs, o as stableCaretRange, p as create, r as isStableVersion, s as update, t as verify, u as tag, v as agentTimedOut, w as WorkspacePackage, x as runAgent, y as parseCodexStdout } from "./verify-CTCK1U-t.js";
+
+export { AGENT_DEFAULT_TIMEOUT_MS, WorkspacePackage, agent, agentAvailable, agentTimedOut, build, bunx, codegen, create, discoverPackageJsons, discoverPackages, errorMessage, fail, format, forwardedUpdateArgs, getDbxtoolsConfig, getProject, git, isStableVersion, latestStableInRange, nonEmptyLines, parseCodexStdout, release, resolveAgentPrompt, runAgent, runBunUpdate, sh, stableCaretRange, tag, toAbsolute, toRelative, update, updateCatalog, verify, writeJson };