@codefast/cli 0.10.0 → 0.11.0

package/dist/audit/prepare.d.ts

@@ -1,70 +1,31 @@
+import type { CodefastConfig } from "#/core/config/schema";
 import { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
- * Shared prelude for `audit rtl`: repo root and the canonicalized scan target with its allowlist.
+ * Shared prelude for an audit: repo root and the canonicalized scan target with its allowlist.
  *
  * @since 0.5.0-canary.6
  */
-export type RtlAuditCommandPrelude = {
+export type AuditCommandPrelude = {
     readonly rootDir: string;
     readonly targetPath: string;
     readonly allowlist: ReadonlyArray<string>;
 };
 /**
- * Loads config and resolves the scan target for `audit rtl`.
+ * Resolves a path that may be absolute or relative to `rootDir`.
  *
  * @since 0.5.0-canary.6
  */
-export declare function prepareRtlAudit(fs: FilesystemPort, args: {
-    readonly currentWorkingDirectory: string;
-    readonly rawTarget: string | undefined;
-}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
-/**
- * Loads config and resolves the scan target for `audit links`.
- *
- * @remarks Defaults to the repo root rather than a configured path: a link audit that only covers one
- * package cannot see the cross-package references that are the ones most likely to rot.
- *
- * @since 0.5.0
- */
-export declare function prepareLinkAudit(fs: FilesystemPort, args: {
-    readonly currentWorkingDirectory: string;
-    readonly rawTarget: string | undefined;
-}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
-/**
- * Loads config and resolves the scan target for `audit imports`.
- *
- * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
- * trees are already excluded by the shared walk.
- *
- * @since 0.10.0
- */
-export declare function prepareImportsAudit(fs: FilesystemPort, args: {
-    readonly currentWorkingDirectory: string;
-    readonly rawTarget: string | undefined;
-}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
-/**
- * Loads config and resolves the scan target for `audit comments`.
- *
- * @remarks Defaults to the repo root: a divider convention that only holds inside one package
- * is not a convention.
- *
- * @since 0.6.0
- */
-export declare function prepareCommentAudit(fs: FilesystemPort, args: {
-    readonly currentWorkingDirectory: string;
-    readonly rawTarget: string | undefined;
-}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+export declare function resolveRepoRelativePath(rootDir: string, maybeRelative: string): string;
 /**
- * Loads config and resolves the scan target for `audit display-names`.
+ * Loads config and resolves the repo root as the scan target, taking the allowlist the caller selects.
  *
- * @remarks Defaults to the repo root: a display name collides across packages, so the convention
- * has to hold across them.
+ * @remarks Every repo-wide audit shares this prelude; only the config key its allowlist comes from differs.
  *
- * @since 0.9.0
+ * @since 0.11.0
  */
-export declare function prepareDisplayNameAudit(fs: FilesystemPort, args: {
+export declare function prepareRepoRootAudit(fs: Filesystem, args: {
     readonly currentWorkingDirectory: string;
     readonly rawTarget: string | undefined;
-}): Promise<Result<RtlAuditCommandPrelude, AppError>>;
+}, selectAllowlist: (config: CodefastConfig) => ReadonlyArray<string>): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/prepare.js

@@ -1,146 +1,24 @@
-import { resolveRepoRelativePath } from "#/audit/cli-schema";
+import path from "node:path";
 import { loadCodefastConfig } from "#/core/config";
 import { AppError, messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
 import { resolveProjectRoot } from "#/core/workspace/resolver";
 /**
- * Loads config and resolves the scan target for `audit rtl`.
+ * Resolves a path that may be absolute or relative to `rootDir`.
  *
  * @since 0.5.0-canary.6
  */
-export async function prepareRtlAudit(fs, args) {
-    let rootDir;
-    try {
-        // Realpath so allowlist keys (`path.relative(rootDir, file)`) stay stable when cwd is a symlink.
-        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
-    }
-    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
-    if (!loadedOutcome.ok) {
-        return loadedOutcome;
-    }
-    const { config } = loadedOutcome.value;
-    const rtlConfig = config.audit?.rtl ?? {};
-    const targetFromCli = args.rawTarget;
-    const targetFromConfig = rtlConfig.target;
-    const resolvedTargetInput = targetFromCli ?? targetFromConfig;
-    if (resolvedTargetInput === undefined) {
-        return err(new AppError("VALIDATION_ERROR", "Missing scan target: pass a path argument or set audit.rtl.target in codefast.config"));
-    }
-    const targetPath = resolveRepoRelativePath(targetFromCli !== undefined ? args.currentWorkingDirectory : rootDir, resolvedTargetInput);
-    if (!fs.existsSync(targetPath)) {
-        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
-    }
-    return ok({
-        rootDir,
-        targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: rtlConfig.allowlist ?? [],
-    });
-}
-/**
- * Loads config and resolves the scan target for `audit links`.
- *
- * @remarks Defaults to the repo root rather than a configured path: a link audit that only covers one
- * package cannot see the cross-package references that are the ones most likely to rot.
- *
- * @since 0.5.0
- */
-export async function prepareLinkAudit(fs, args) {
-    let rootDir;
-    try {
-        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
-    }
-    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
-    if (!loadedOutcome.ok) {
-        return loadedOutcome;
-    }
-    const linksConfig = loadedOutcome.value.config.audit?.links ?? {};
-    const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
-    if (!fs.existsSync(targetPath)) {
-        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
-    }
-    return ok({
-        rootDir,
-        targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: linksConfig.allowlist ?? [],
-    });
-}
-/**
- * Loads config and resolves the scan target for `audit imports`.
- *
- * @remarks Defaults to the repo root: the import policy is repo-wide, and generated or vendored
- * trees are already excluded by the shared walk.
- *
- * @since 0.10.0
- */
-export async function prepareImportsAudit(fs, args) {
-    let rootDir;
-    try {
-        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
-    }
-    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
-    if (!loadedOutcome.ok) {
-        return loadedOutcome;
-    }
-    const importsConfig = loadedOutcome.value.config.audit?.imports ?? {};
-    const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
-    if (!fs.existsSync(targetPath)) {
-        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
-    }
-    return ok({
-        rootDir,
-        targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: importsConfig.allowlist ?? [],
-    });
-}
-/**
- * Loads config and resolves the scan target for `audit comments`.
- *
- * @remarks Defaults to the repo root: a divider convention that only holds inside one package
- * is not a convention.
- *
- * @since 0.6.0
- */
-export async function prepareCommentAudit(fs, args) {
-    let rootDir;
-    try {
-        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
-    }
-    catch (caughtError) {
-        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
-    }
-    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
-    if (!loadedOutcome.ok) {
-        return loadedOutcome;
-    }
-    const commentsConfig = loadedOutcome.value.config.audit?.comments ?? {};
-    const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
-    if (!fs.existsSync(targetPath)) {
-        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
-    }
-    return ok({
-        rootDir,
-        targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: commentsConfig.allowlist ?? [],
-    });
+export function resolveRepoRelativePath(rootDir, maybeRelative) {
+    return path.isAbsolute(maybeRelative) ? path.resolve(maybeRelative) : path.resolve(rootDir, maybeRelative);
 }
 /**
- * Loads config and resolves the scan target for `audit display-names`.
+ * Loads config and resolves the repo root as the scan target, taking the allowlist the caller selects.
  *
- * @remarks Defaults to the repo root: a display name collides across packages, so the convention
- * has to hold across them.
+ * @remarks Every repo-wide audit shares this prelude; only the config key its allowlist comes from differs.
  *
- * @since 0.9.0
+ * @since 0.11.0
  */
-export async function prepareDisplayNameAudit(fs, args) {
+export async function prepareRepoRootAudit(fs, args, selectAllowlist) {
     let rootDir;
     try {
         rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
@@ -152,7 +30,6 @@ export async function prepareDisplayNameAudit(fs, args) {
     if (!loadedOutcome.ok) {
         return loadedOutcome;
     }
-    const displayNamesConfig = loadedOutcome.value.config.audit?.displayNames ?? {};
     const targetPath = args.rawTarget === undefined ? rootDir : resolveRepoRelativePath(args.currentWorkingDirectory, args.rawTarget);
     if (!fs.existsSync(targetPath)) {
         return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
@@ -160,6 +37,6 @@ export async function prepareDisplayNameAudit(fs, args) {
     return ok({
         rootDir,
         targetPath: fs.canonicalPathSync(targetPath),
-        allowlist: displayNamesConfig.allowlist ?? [],
+        allowlist: selectAllowlist(loadedOutcome.value.config),
     });
 }

package/dist/audit/rtl/cli-result.d.ts

@@ -0,0 +1,13 @@
+import type { RtlAuditResult } from "#/audit/domain/types";
+/**
+ * Exit `1` when any non-allowlisted violation remains.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function exitCodeForRtlAuditResult(result: RtlAuditResult): number;
+/**
+ * Machine-readable RTL audit summary for `--json`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function formatRtlAuditJsonOutput(result: RtlAuditResult, rootDir: string): string;

package/dist/audit/rtl/cli-result.js

@@ -0,0 +1,22 @@
+import { CLI_EXIT_GENERAL_ERROR, CLI_EXIT_SUCCESS } from "#/core/exit-codes";
+/**
+ * Exit `1` when any non-allowlisted violation remains.
+ *
+ * @since 0.5.0-canary.6
+ */
+export function exitCodeForRtlAuditResult(result) {
+    return result.violationCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Machine-readable RTL audit summary for `--json`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export function formatRtlAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.violationCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}

package/dist/audit/rtl/cli-schema.d.ts

@@ -0,0 +1,18 @@
+import * as z from "zod";
+/**
+ * Resolved request for a single RTL audit run.
+ *
+ * @since 0.5.0-canary.6
+ */
+export type RtlAuditRunRequest = {
+    readonly rootDir: string;
+    readonly targetPath: string;
+    readonly allowlist?: ReadonlyArray<string> | undefined;
+    readonly json: boolean;
+};
+/**
+ * Zod schema for {@link RtlAuditRunRequest}.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare const rtlAuditRunRequestSchema: z.ZodType<RtlAuditRunRequest>;

package/dist/audit/rtl/cli-schema.js

@@ -0,0 +1,12 @@
+import * as z from "zod";
+/**
+ * Zod schema for {@link RtlAuditRunRequest}.
+ *
+ * @since 0.5.0-canary.6
+ */
+export const rtlAuditRunRequestSchema = z.object({
+    rootDir: z.string().min(1),
+    targetPath: z.string().min(1),
+    allowlist: z.array(z.string()).optional(),
+    json: z.boolean(),
+});

package/dist/audit/{domain → rtl/domain}/audit-file.js

@@ -1,5 +1,5 @@
-import { DIRECTION_RESOLVED_VARIANT, PHYSICAL_SIDE_VARIANT, RTL_MAPPINGS, RTL_REVERSE_MAPPINGS, RTL_SWAP_MAPPINGS, RTL_TRANSLATE_X_MAPPINGS, SLIDE_PREFIXES, } from "#/audit/domain/mappings";
-import { collectTokens } from "#/audit/domain/tokenize";
+import { DIRECTION_RESOLVED_VARIANT, PHYSICAL_SIDE_VARIANT, RTL_MAPPINGS, RTL_REVERSE_MAPPINGS, RTL_SWAP_MAPPINGS, RTL_TRANSLATE_X_MAPPINGS, SLIDE_PREFIXES, } from "#/audit/rtl/domain/mappings";
+import { collectTokens } from "#/audit/rtl/domain/tokenize";
 /**
  * A token satisfies an "rtl companion" requirement when the same file has a
  * token whose variants include `rtl` and whose value matches. Variant order

package/dist/audit/rtl/output.d.ts

@@ -0,0 +1,7 @@
+import type { RtlAuditResult } from "#/audit/domain/types";
+/**
+ * Human-readable RTL audit report (matches the former packages/ui script shape).
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function presentRtlAuditResult(result: RtlAuditResult): void;

package/dist/audit/rtl/output.js

@@ -0,0 +1,21 @@
+import { logger } from "#/core/logger";
+/**
+ * Human-readable RTL audit report (matches the former packages/ui script shape).
+ *
+ * @since 0.5.0-canary.6
+ */
+export function presentRtlAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, suggestion } of file.violations) {
+            logger.out(`  ${line}: ${raw} → ${suggestion}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.violationCount > 0) {
+        logger.out(`\n✖ ${result.violationCount} RTL violation(s)${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ No physical-direction classes outside the allowlist${allowlistSuffix}`);
+    }
+}

package/dist/audit/rtl/prepare.d.ts

@@ -0,0 +1,13 @@
+import type { AuditCommandPrelude } from "#/audit/prepare";
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * Loads config and resolves the scan target for `audit rtl`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export declare function prepareRtlAudit(fs: Filesystem, args: {
+    readonly currentWorkingDirectory: string;
+    readonly rawTarget: string | undefined;
+}): Promise<Result<AuditCommandPrelude, AppError>>;

package/dist/audit/rtl/prepare.js

@@ -0,0 +1,41 @@
+import { resolveRepoRelativePath } from "#/audit/prepare";
+import { loadCodefastConfig } from "#/core/config";
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
+/**
+ * Loads config and resolves the scan target for `audit rtl`.
+ *
+ * @since 0.5.0-canary.6
+ */
+export async function prepareRtlAudit(fs, args) {
+    let rootDir;
+    try {
+        // Realpath so allowlist keys (`path.relative(rootDir, file)`) stay stable when cwd is a symlink.
+        rootDir = fs.canonicalPathSync(resolveProjectRoot(args.currentWorkingDirectory, fs).rootDir);
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+    const loadedOutcome = await loadCodefastConfig(rootDir, fs);
+    if (!loadedOutcome.ok) {
+        return loadedOutcome;
+    }
+    const { config } = loadedOutcome.value;
+    const rtlConfig = config.audit?.rtl ?? {};
+    const targetFromCli = args.rawTarget;
+    const targetFromConfig = rtlConfig.target;
+    const resolvedTargetInput = targetFromCli ?? targetFromConfig;
+    if (resolvedTargetInput === undefined) {
+        return err(new AppError("VALIDATION_ERROR", "Missing scan target: pass a path argument or set audit.rtl.target in codefast.config"));
+    }
+    const targetPath = resolveRepoRelativePath(targetFromCli !== undefined ? args.currentWorkingDirectory : rootDir, resolvedTargetInput);
+    if (!fs.existsSync(targetPath)) {
+        return err(new AppError("NOT_FOUND", `Not found: ${targetPath}`));
+    }
+    return ok({
+        rootDir,
+        targetPath: fs.canonicalPathSync(targetPath),
+        allowlist: rtlConfig.allowlist ?? [],
+    });
+}

package/dist/audit/{run.d.ts → rtl/run.d.ts}

@@ -1,13 +1,13 @@
 import type { RtlAuditResult } from "#/audit/domain/types";
 import { AppError } from "#/core/errors";
-import type { FilesystemPort } from "#/core/filesystem/port";
+import type { Filesystem } from "#/core/filesystem/filesystem";
 import type { Result } from "#/core/result";
 /**
  * Scans a target path for physical-direction Tailwind class violations.
  *
  * @since 0.5.0-canary.6
  */
-export declare function runRtlAudit(fs: FilesystemPort, args: {
+export declare function runRtlAudit(fs: Filesystem, args: {
     readonly rootDir: string;
     readonly targetPath: string;
     readonly allowlist: ReadonlyArray<string>;

package/dist/audit/{run.js → rtl/run.js}

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { auditFileContent } from "#/audit/domain/audit-file";
+import { auditFileContent } from "#/audit/rtl/domain/audit-file";
 import { AppError, messageFrom } from "#/core/errors";
 import { err, ok } from "#/core/result";
 import { walkTsxFiles } from "#/core/workspace/typescript-walk";

package/dist/core/cli/command-pipeline.d.ts

@@ -0,0 +1,91 @@
+import type { Command } from "commander";
+import type { ZodType } from "zod";
+import type { GlobalCliOptions } from "#/core/cli/global-options";
+import type { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * The options every command shares: the `--json` machine-output flag. Per-command option shapes extend this.
+ *
+ * @since 0.11.0
+ */
+export interface BaseCommandOptions {
+    readonly json?: boolean | undefined;
+}
+/**
+ * A pipeline's `prepare` slot: resolves the argv context (cwd, positional, global options) into the command's prelude.
+ *
+ * @since 0.11.0
+ */
+export type CommandPrepare<Prelude> = (fs: Filesystem, input: {
+    readonly currentWorkingDirectory: string;
+    readonly rawArg: string | undefined;
+    readonly globals: GlobalCliOptions;
+}) => Promise<Result<Prelude, AppError>>;
+/** The prelude and options a request is built from, before the run. */
+interface BuildInput<Prelude, Opts> {
+    readonly prelude: Prelude;
+    readonly opts: Opts;
+    readonly globals: GlobalCliOptions;
+}
+/** The run result and its surrounding context, for the report phase. */
+interface ReportInput<Prelude, RunResult, Presenter, Opts> {
+    readonly result: RunResult;
+    readonly prelude: Prelude;
+    readonly opts: Opts;
+    readonly presenter: Presenter | undefined;
+    readonly elapsedSeconds: number;
+}
+/**
+ * The invariant shape every workspace command and subcommand shares: resolve a prelude, build and
+ * validate a request, run it, then report to one of two audiences and record a single exit code.
+ *
+ * @remarks The optional slots carry the per-command variations — a working-tree guard and a streaming
+ * presenter — so the control flow itself is written once.
+ *
+ * @since 0.11.0
+ */
+export interface CommandPipeline<Prelude, Request, RunResult, Presenter = never, Opts extends BaseCommandOptions = BaseCommandOptions> {
+    readonly name?: string | undefined;
+    readonly description?: string | undefined;
+    readonly positional?: {
+        readonly name: string;
+        readonly help: string;
+    } | undefined;
+    readonly jsonHelp?: string | undefined;
+    readonly configureArgv?: ((command: Command) => void) | undefined;
+    readonly prepare: CommandPrepare<Prelude>;
+    readonly guard?: ((input: {
+        readonly prelude: Prelude;
+        readonly opts: Opts;
+    }) => Promise<Result<void, AppError>>) | undefined;
+    readonly schema: ZodType<Request>;
+    readonly buildRequest: (input: BuildInput<Prelude, Opts>) => unknown;
+    readonly createPresenter?: ((input: BuildInput<Prelude, Opts>) => Presenter) | undefined;
+    readonly run: (fs: Filesystem, request: Request, presenter: Presenter | undefined) => Promise<Result<RunResult, AppError>>;
+    readonly presentHuman?: ((input: ReportInput<Prelude, RunResult, Presenter, Opts>) => void) | undefined;
+    readonly formatJson: (input: ReportInput<Prelude, RunResult, Presenter, Opts>) => string;
+    readonly exitCode: (result: RunResult) => number;
+}
+/**
+ * A pipeline that names itself, so it can register as a subcommand under a parent command.
+ *
+ * @since 0.11.0
+ */
+export type NamedCommandPipeline<Prelude, Request, RunResult, Presenter = never, Opts extends BaseCommandOptions = BaseCommandOptions> = CommandPipeline<Prelude, Request, RunResult, Presenter, Opts> & {
+    readonly name: string;
+    readonly description: string;
+};
+/**
+ * Wires a pipeline onto a named Command: the shared positional, `--json`, any extra options, and the action.
+ *
+ * @since 0.11.0
+ */
+export declare function applyCommandPipeline<Prelude, Request, RunResult, Presenter, Opts extends BaseCommandOptions>(command: Command, fs: Filesystem, pipeline: CommandPipeline<Prelude, Request, RunResult, Presenter, Opts>): Command;
+/**
+ * Registers a pipeline as a subcommand under `parent`, taking its name and description from the pipeline.
+ *
+ * @since 0.11.0
+ */
+export declare function registerPipelineSubcommand<Prelude, Request, RunResult, Presenter, Opts extends BaseCommandOptions>(parent: Command, fs: Filesystem, pipeline: NamedCommandPipeline<Prelude, Request, RunResult, Presenter, Opts>): void;
+export {};

package/dist/core/cli/command-pipeline.js

@@ -0,0 +1,83 @@
+import process from "node:process";
+import { globalCliCommanderOptionsSchema } from "#/core/cli/global-options";
+import { readOptionalPositionalArg } from "#/core/cli/positional";
+import { consumeCliAppError } from "#/core/cli/result-handle";
+import { logger } from "#/core/logger";
+import { parseWithSchema } from "#/core/schema-parse";
+const DEFAULT_JSON_HELP = "Print one JSON summary on stdout (suppresses human progress)";
+function readGlobalOptions(command) {
+    return (command.optsWithGlobals?.() ?? command.opts());
+}
+function makeAction(fs, pipeline) {
+    return async (rawArg, opts, command) => {
+        const globalsOutcome = parseWithSchema(globalCliCommanderOptionsSchema, readGlobalOptions(command));
+        if (!consumeCliAppError(globalsOutcome)) {
+            return;
+        }
+        const globals = globalsOutcome.value;
+        const prelude = await pipeline.prepare(fs, {
+            currentWorkingDirectory: process.cwd(),
+            rawArg: readOptionalPositionalArg(rawArg),
+            globals,
+        });
+        if (!consumeCliAppError(prelude)) {
+            return;
+        }
+        if (pipeline.guard) {
+            const guarded = await pipeline.guard({ prelude: prelude.value, opts });
+            if (!consumeCliAppError(guarded)) {
+                return;
+            }
+        }
+        const parsed = parseWithSchema(pipeline.schema, pipeline.buildRequest({ prelude: prelude.value, opts, globals }));
+        if (!consumeCliAppError(parsed)) {
+            return;
+        }
+        const json = !!opts.json;
+        const presenter = !json && pipeline.createPresenter
+            ? pipeline.createPresenter({ prelude: prelude.value, opts, globals })
+            : undefined;
+        const startedAt = performance.now();
+        const outcome = await pipeline.run(fs, parsed.value, presenter);
+        if (!consumeCliAppError(outcome)) {
+            return;
+        }
+        const elapsedSeconds = (performance.now() - startedAt) / 1000;
+        const report = {
+            result: outcome.value,
+            prelude: prelude.value,
+            opts,
+            presenter,
+            elapsedSeconds,
+        };
+        if (json) {
+            logger.out(pipeline.formatJson(report));
+        }
+        else {
+            pipeline.presentHuman?.(report);
+        }
+        process.exitCode = pipeline.exitCode(outcome.value);
+    };
+}
+/**
+ * Wires a pipeline onto a named Command: the shared positional, `--json`, any extra options, and the action.
+ *
+ * @since 0.11.0
+ */
+export function applyCommandPipeline(command, fs, pipeline) {
+    if (pipeline.positional) {
+        command.argument(pipeline.positional.name, pipeline.positional.help);
+    }
+    command.option("--json", pipeline.jsonHelp ?? DEFAULT_JSON_HELP, false);
+    pipeline.configureArgv?.(command);
+    command.action(makeAction(fs, pipeline));
+    return command;
+}
+/**
+ * Registers a pipeline as a subcommand under `parent`, taking its name and description from the pipeline.
+ *
+ * @since 0.11.0
+ */
+export function registerPipelineSubcommand(parent, fs, pipeline) {
+    applyCommandPipeline(parent.command(pipeline.name).description(pipeline.description), fs, pipeline);
+}

package/dist/core/cli/global-options.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 /**
  * The validated global CLI options shared by every subcommand.
  *

package/dist/core/cli/global-options.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import * as z from "zod";
 /**
  * Commander global opts shape validated before mirror prelude (`color` from `--no-color`).
  *

package/dist/core/cli/resolve-root.d.ts

@@ -0,0 +1,9 @@
+import { AppError } from "#/core/errors";
+import type { Filesystem } from "#/core/filesystem/filesystem";
+import type { Result } from "#/core/result";
+/**
+ * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
+ *
+ * @since 0.11.0
+ */
+export declare function resolveProjectRootResult(fs: Filesystem, currentWorkingDirectory: string): Result<string, AppError>;

package/dist/core/cli/resolve-root.js

@@ -0,0 +1,16 @@
+import { AppError, messageFrom } from "#/core/errors";
+import { err, ok } from "#/core/result";
+import { resolveProjectRoot } from "#/core/workspace/resolver";
+/**
+ * Resolves the project root as a `Result`, mapping a resolution failure to an `INFRA_FAILURE` error.
+ *
+ * @since 0.11.0
+ */
+export function resolveProjectRootResult(fs, currentWorkingDirectory) {
+    try {
+        return ok(resolveProjectRoot(currentWorkingDirectory, fs).rootDir);
+    }
+    catch (caughtError) {
+        return err(new AppError("INFRA_FAILURE", messageFrom(caughtError), caughtError));
+    }
+}