cli — Functions

Functions and classes exported by this package.

configureLogger(options)

Configures the global forgeLogger based on CLI flags. Call this once at the start of a command's run() handler to align consola's output level with the user's intent: - quiet or json sets level to 0 (silent) so only LAFS output appears. - verbose sets level to 4 (debug) for maximum detail. - Default level is 3 (info) which covers info, warn, error, and success.

Signature

(options: ForgeLoggerOptions) => void

Parameters

Example

import { configureLogger, forgeLogger } from "./forge-logger.js";
configureLogger({ quiet: args.quiet, json: args.json, verbose: args.verbose });
forgeLogger.info("This respects the configured level");

emitResult(output, flags, humanFormatter)

Wraps a command result in a LAFS envelope and emits it. Output format is determined by LAFS flag resolution: - TTY terminals default to human-readable output. - Non-TTY (piped, CI, agents) defaults to JSON. - Explicit --json or --human flags always take precedence. On failure, the full result is included alongside the error so agents get actionable data (e.g., suggestedFix) in a single response.

Signature

<T>(output: CommandOutput<T>, flags: OutputFlags, humanFormatter: (data: T, output: CommandOutput<T>) => string) => void

Parameters

Example

import { emitResult } from "@forge-ts/cli/output";
emitResult(output, { human: true }, (data) => `Done: ${data.summary.duration}ms`);

resolveExitCode(output)

Returns the LAFS-compliant exit code for a command output.

Signature

(output: CommandOutput<unknown>) => number

Parameters

Returns — 0 on success, 1 on validation/check failure.

runAudit(args)

Reads the audit log and returns a typed command output.

Signature

(args: AuditArgs) => CommandOutput<AuditResult>

Parameters

Returns — A typed CommandOutput<AuditResult>.

Example

import { runAudit } from "@forge-ts/cli/commands/audit";
const output = await runAudit({ cwd: process.cwd(), limit: 10 });
console.log(output.data.count); // number of events returned

runBarometer(args)

Runs the barometer generation pass. Loads the project config, walks the symbol graph, extracts testable facts from five categories, generates questions with ground-truth answers, and writes the result to .forge/barometer.json.

Signature

(args: BarometerArgs) => Promise<CommandOutput<BarometerResult>>

Parameters

Returns — A typed CommandOutput<BarometerResult>.

Example

import { runBarometer } from "@forge-ts/cli/commands/barometer";
const output = await runBarometer({ cwd: process.cwd() });
console.log(`Generated ${output.data.questions.length} questions`);

runBarometerScore(args)

Scores agent answers against the barometer answer key.

Signature

(args: { cwd?: string; answersPath: string; }) => Promise<CommandOutput<BarometerScoreResult>>

Parameters

Returns — A typed CommandOutput<BarometerScoreResult>.

Example

import { runBarometerScore } from "@forge-ts/cli/commands/barometer";
const output = await runBarometerScore({ answersPath: "answers.json" });
console.log(`Score: ${output.data.score}%`);

runBuild(args)

Runs the full build pipeline and returns a typed command output.

Signature

(args: BuildArgs) => Promise<CommandOutput<BuildResult>>

Parameters

Returns — A typed CommandOutput<BuildResult>.

Example

import { runBuild } from "@forge-ts/cli/commands/build";
const output = await runBuild({ cwd: process.cwd() });
console.log(output.success); // true if all steps succeeded

runBypassCreate(args)

Runs the bypass creation: creates a new bypass record with budget enforcement.

Signature

(args: { cwd?: string; reason: string; rule?: string; }) => Promise<CommandOutput<BypassCreateResult>>

Parameters

Returns — A typed CommandOutput<BypassCreateResult>.

Example

import { runBypassCreate } from "@forge-ts/cli/commands/bypass";
const output = await runBypassCreate({
  cwd: process.cwd(),
  reason: "hotfix for release",
  rule: "E009",
});
console.log(output.data.remainingBudget);

runBypassStatus(args)

Runs the bypass status query: shows active bypasses and remaining budget.

Signature

(args: { cwd?: string; }) => Promise<CommandOutput<BypassStatusResult>>

Parameters

Returns — A typed CommandOutput<BypassStatusResult>.

Example

import { runBypassStatus } from "@forge-ts/cli/commands/bypass";
const output = await runBypassStatus({ cwd: process.cwd() });
console.log(output.data.activeBypasses.length);

getStagedFiles(cwd)

Returns the list of staged .ts/.tsx files (relative paths) by querying git. Returns null when git is unavailable or the working directory is not a git repository. Deleted files are excluded. The command is a fixed string with no interpolated user input, so shell injection is not a concern here.

Signature

(cwd: string) => string[] | null

Parameters

Returns — Array of relative file paths, or null on failure.

runCheck(args)

Runs the TSDoc enforcement pass and returns a typed command output.

Signature

(args: CheckArgs) => Promise<CommandOutput<CheckResult>>

Parameters

Returns — A typed CommandOutput<CheckResult>.

Example

import { runCheck } from "@forge-ts/cli/commands/check";
const output = await runCheck({ cwd: process.cwd() });
console.log(output.data.summary.errors); // number of TSDoc errors found

runDocsDev(args)

Starts the local dev server for the configured SSG target. Reads gen.ssgTarget from the forge-ts config, resolves the adapter, and spawns the platform's dev server in the output directory.

Signature

(args: { cwd?: string; target?: string; port?: string; }) => Promise<void>

Parameters

Returns — A promise that resolves when the server exits.

Example

import { runDocsDev } from "@forge-ts/cli";
await runDocsDev({ cwd: "./my-project" });

readPkgJson(rootDir)

Read and parse package.json from a project root. Detects indent style and trailing newline for lossless round-tripping. Returns null if the file doesn't exist or can't be parsed.

Signature

(rootDir: string) => PkgJson | null

Parameters

Returns — Parsed package.json with formatting metadata, or null.

serializePkgJson(pkg)

Serialize a package.json object preserving original formatting.

Signature

(pkg: PkgJson) => string

Parameters

Returns — Formatted JSON string ready to write to disk.

writePkgJson(pkg)

Write a modified package.json back to disk, preserving formatting.

Signature

(pkg: PkgJson) => Promise<void>

Parameters

addScripts(pkg, scripts)

Add scripts to package.json idempotently. Only adds scripts where the key doesn't already exist. Never overwrites existing script values. Returns the list of keys added.

Signature

(pkg: PkgJson, scripts: Record<string, string>) => string[]

Parameters

Returns — Array of script keys that were added (empty if all already existed).

detectHookManager(rootDir)

Detects which hook manager is present in the project. Checks for: - husky: .husky/ directory or husky in package.json devDependencies - lefthook: lefthook.yml or lefthook in package.json devDependencies

Signature

(rootDir: string) => HookManager

Parameters

Returns — The detected hook manager, or "none" if neither is found.

Example

import { detectHookManager } from "@forge-ts/cli/commands/init-hooks";
const manager = detectHookManager("/path/to/project");
console.log(manager); // "husky" | "lefthook" | "none"

generateHuskyHook()

Generates the husky pre-commit hook file content (modern husky v9+).

Signature

() => string

generateHuskyPrePushHook()

Generates the husky pre-push hook file content (modern husky v9+).

Signature

() => string

generateLefthookBlock()

Generates the lefthook block with both pre-commit and pre-push sections.

Signature

() => string

detectVersionGuard(rootDir)

Checks whether a versionguard config file exists in the project root. When detected, forge-ts appends versionguard's hook lines to the generated hook files so both tools run cooperatively.

Signature

(rootDir: string) => boolean

Parameters

Returns — True when a versionguard config file is found.

Example

import { detectVersionGuard } from "@forge-ts/cli/commands/init-hooks";
if (detectVersionGuard("/path/to/project")) {
  console.log("VersionGuard detected — adding cooperative hooks");
}

runInitHooks(args)

Scaffolds git hook integration for the project. Detects the hook manager (husky or lefthook), generates appropriate hook files, and reports what was written.

Signature

(args: InitHooksArgs) => Promise<CommandOutput<InitHooksResult>>

Parameters

Returns — A typed CommandOutput<InitHooksResult>.

Example

import { runInitHooks } from "@forge-ts/cli/commands/init-hooks";
const output = await runInitHooks({ cwd: "/my/project" });
console.log(output.data.files); // [".husky/pre-commit"]

detectEnvironment(rootDir)

Detects the project environment by checking for files and dependencies.

Signature

(rootDir: string) => InitProjectEnvironment

Parameters

Returns — The detected environment.

buildTsdocContent(customTags)

Builds tsdoc.json content, merging in customTags from the forge config. When customTags is non-empty, the written tsdoc.json includes both tagDefinitions and supportForTags entries so that the TSDoc parser (and any editor extensions) recognise the custom tags.

Signature

(customTags?: Array<{ tagName: string; syntaxKind: "block" | "inline" | "modifier"; }>) => string

Parameters

Returns — A JSON string for tsdoc.json.

runInitProject(args)

Runs the full project init flow.

Signature

(args: InitProjectArgs) => Promise<CommandOutput<InitProjectResult>>

Parameters

Returns — A typed CommandOutput<InitProjectResult>.

Example

import { runInitProject } from "@forge-ts/cli/commands/init-project";
const output = await runInitProject({ cwd: process.cwd() });
console.log(output.data.created); // ["forge-ts.config.ts", "tsdoc.json"]

runDoctor(args)

Runs the doctor integrity check flow.

Signature

(args: DoctorArgs) => Promise<CommandOutput<DoctorResult>>

Parameters

Returns — A typed CommandOutput<DoctorResult>.

Example

import { runDoctor } from "@forge-ts/cli/commands/doctor";
const output = await runDoctor({ cwd: process.cwd(), fix: false });
console.log(output.data.summary); // { passed: 7, warnings: 2, errors: 1, info: 0 }

runInitDocs(args)

Scaffolds a documentation site for the target SSG platform. Resolves the target from args, validates it, checks for an existing scaffold, calls the adapter's scaffold() method, and writes all files produced by the manifest to outDir.

Signature

(args: InitDocsArgs) => Promise<CommandOutput<InitDocsResult>>

Parameters

Returns — A typed CommandOutput<InitDocsResult>.

Example

import { runInitDocs } from "@forge-ts/cli/commands/init-docs";
const output = await runInitDocs({ target: "mintlify", cwd: process.cwd() });
console.log(output.data.files); // list of created file paths

runLock(args)

Runs the lock command: reads current config and creates .forge-lock.json.

Signature

(args: { cwd?: string; }) => Promise<CommandOutput<LockResult>>

Parameters

Returns — A typed CommandOutput<LockResult>.

Example

import { runLock } from "@forge-ts/cli/commands/lock";
const output = await runLock({ cwd: process.cwd() });
console.log(output.data.locked.rules); // number of rules locked

runPrepublish(args)

Runs the prepublish safety gate: check then build. If the check step fails, the build step is skipped entirely. Both steps use the same project root (cwd).

Signature

(args: PrepublishArgs) => Promise<CommandOutput<PrepublishResult>>

Parameters

Returns — A typed CommandOutput<PrepublishResult>.

Example

import { runPrepublish } from "@forge-ts/cli/commands/prepublish";
const output = await runPrepublish({ cwd: process.cwd() });
if (!output.success) process.exit(1);

runTest(args)

Runs the doctest pipeline and returns a typed command output.

Signature

(args: TestArgs) => Promise<CommandOutput<TestResult>>

Parameters

Returns — A typed CommandOutput<TestResult>.

Example

import { runTest } from "@forge-ts/cli/commands/test";
const output = await runTest({ cwd: process.cwd() });
console.log(output.data.summary.passed); // number of passing doctests

runUnlock(args)

Runs the unlock command: removes .forge-lock.json with a mandatory reason.

Signature

(args: { cwd?: string; reason: string; }) => Promise<CommandOutput<UnlockResult>>

Parameters

Returns — A typed CommandOutput<UnlockResult>.

Example

import { runUnlock } from "@forge-ts/cli/commands/unlock";
const output = await runUnlock({ cwd: process.cwd(), reason: "Relaxing rules for migration" });
console.log(output.data.success); // true