outfitter 0.3.2 → 0.3.3

package/dist/shared/outfitter-5j7zee11.d.ts

@@ -0,0 +1,180 @@
+import { VersionConflict } from "./outfitter-109s75x0.js";
+import { MigrationChange } from "./outfitter-y37yfehn.js";
+import { OutputMode as OutputMode3 } from "@outfitter/cli/types";
+import { OutfitterError as OutfitterError2 } from "@outfitter/contracts";
+import { Result } from "@outfitter/contracts";
+import { OutputMode } from "@outfitter/cli/types";
+/** Options controlling how upgrade results are rendered. */
+interface PrintUpgradeResultsOptions {
+	readonly all?: boolean;
+	readonly cwd?: string;
+	readonly dryRun?: boolean;
+	readonly guide?: boolean;
+	readonly mode?: OutputMode;
+}
+/**
+* Format and output upgrade results.
+*
+* @param result - Upgrade scan/apply result to render
+* @param options - Display options (output mode, guide, dry-run hints)
+*/
+declare function printUpgradeResults(result: UpgradeResult, options?: PrintUpgradeResultsOptions): Promise<void>;
+import { OutputMode as OutputMode2 } from "@outfitter/cli/types";
+import { OutfitterError } from "@outfitter/contracts";
+/** Terminal disposition of an upgrade run (written into the report). */
+type UpgradeReportStatus = "dry_run" | "no_updates" | "cancelled" | "skipped_non_interactive" | "applied" | "failed";
+/** Snapshot of effective flags for this upgrade run. */
+interface UpgradeReportFlags {
+	readonly all: boolean;
+	readonly dryRun: boolean;
+	readonly interactive: boolean;
+	readonly noCodemods: boolean;
+	readonly outputMode: OutputMode2 | null;
+	readonly yes: boolean;
+}
+/** Machine-readable upgrade report written to `.outfitter/reports/upgrade.json`. */
+interface UpgradeReport {
+	readonly $schema: "https://outfitter.dev/reports/upgrade/v1";
+	readonly applied: boolean;
+	readonly checkedAt: string;
+	readonly codemods?: CodemodSummary;
+	readonly conflicts?: readonly VersionConflict[];
+	readonly cwd: string;
+	readonly error?: {
+		readonly message: string;
+		readonly category: string;
+		readonly context?: Record<string, unknown>;
+	};
+	readonly excluded: {
+		readonly breaking: readonly string[];
+	};
+	readonly finishedAt: string;
+	readonly flags: UpgradeReportFlags;
+	readonly packages: readonly PackageVersionInfo[];
+	readonly startedAt: string;
+	readonly status: UpgradeReportStatus;
+	readonly summary: {
+		readonly total: number;
+		readonly available: number;
+		readonly breaking: number;
+		readonly applied: number;
+	};
+	readonly unknownPackages?: readonly string[];
+	readonly workspaceRoot: string | null;
+}
+/** Contextual metadata passed alongside the result when writing a report. */
+interface WriteUpgradeReportMeta {
+	readonly error?: OutfitterError;
+	readonly options: UpgradeOptions;
+	readonly startedAt: Date;
+	readonly status: UpgradeReportStatus;
+	readonly workspaceRoot: string | null;
+}
+/**
+* Best-effort report writer.
+*
+* Report I/O failures should not change the primary command result.
+*/
+declare function writeUpgradeReportSafely(cwd: string, result: UpgradeResult, meta: WriteUpgradeReportMeta): void;
+/** Input options for `runUpgrade`. */
+interface UpgradeOptions {
+	/** Include breaking changes in the upgrade */
+	readonly all?: boolean;
+	/** Working directory (defaults to cwd) */
+	readonly cwd: string;
+	/** Preview only — no mutations, no prompt */
+	readonly dryRun?: boolean;
+	/** Show migration guide */
+	readonly guide?: boolean;
+	/** Filter to specific package names (scan + guides) */
+	readonly guidePackages?: readonly string[];
+	/** Whether interactive prompts are enabled (false in CI) */
+	readonly interactive?: boolean;
+	/** Skip automatic codemod execution during upgrade */
+	readonly noCodemods?: boolean;
+	/** Output mode */
+	readonly outputMode?: OutputMode3;
+	/** Auto-confirm without prompting */
+	readonly yes?: boolean;
+}
+/** Version metadata for a single installed @outfitter/* package. */
+interface PackageVersionInfo {
+	/** Whether the update contains breaking changes (major bump) */
+	readonly breaking: boolean;
+	/** Currently installed version */
+	readonly current: string;
+	/** Latest available version from npm (null if query failed) */
+	readonly latest: string | null;
+	/** Full package name */
+	readonly name: string;
+	/** Whether an update is available */
+	readonly updateAvailable: boolean;
+}
+/** Summary of codemods executed during --apply. */
+interface CodemodSummary {
+	/** Total files changed across all codemods */
+	readonly changedFiles: readonly string[];
+	/** Number of codemods executed */
+	readonly codemodCount: number;
+	/** Errors encountered during codemod execution */
+	readonly errors: readonly string[];
+}
+/** Complete output of a single upgrade run. */
+interface UpgradeResult {
+	/** Whether mutations were made (--apply was used and changes were written) */
+	readonly applied: boolean;
+	/** Package names that were updated in package.json */
+	readonly appliedPackages: string[];
+	/** Codemod execution summary (populated when --apply runs codemods) */
+	readonly codemods?: CodemodSummary;
+	/** Version conflicts found across workspace manifests */
+	readonly conflicts?: readonly VersionConflict[];
+	/** Structured migration guides (populated when --guide is used) */
+	readonly guides?: readonly MigrationGuide[];
+	/** Whether any update is a breaking change */
+	readonly hasBreaking: boolean;
+	/** Package version info */
+	readonly packages: PackageVersionInfo[];
+	/** Package names skipped because they contain breaking changes */
+	readonly skippedBreaking: string[];
+	/** Total packages checked */
+	readonly total: number;
+	/** Package names that were requested but not found in the workspace */
+	readonly unknownPackages?: readonly string[];
+	/** Number of packages with updates available */
+	readonly updatesAvailable: number;
+}
+/**
+* Run the upgrade command — detect installed versions and query npm for latest.
+*
+* Default flow: scan → classify → prompt → apply.
+* `--dry-run` returns a report without mutation.
+* `--all` includes breaking changes.
+* `--yes` or `--non-interactive` bypasses the prompt.
+*/
+declare function runUpgrade(options: UpgradeOptions): Promise<Result<UpgradeResult, OutfitterError2>>;
+type GuidePackageVersionInfo = PackageVersionInfo;
+/** Structured migration guide for a single package upgrade. */
+interface MigrationGuide {
+	/** Whether this is a breaking change */
+	readonly breaking: boolean;
+	/** Structured changes from migration frontmatter, if available */
+	readonly changes?: readonly MigrationChange[];
+	/** Currently installed version */
+	readonly fromVersion: string;
+	/** The @outfitter/* package name */
+	readonly packageName: string;
+	/** Migration step strings (empty if no guide exists) */
+	readonly steps: readonly string[];
+	/** Latest available version */
+	readonly toVersion: string;
+}
+/**
+* Build structured migration guides for packages with available updates.
+*
+* For each package with an update, produces a `MigrationGuide` with steps
+* extracted from migration docs (if a migrations directory is available).
+* Packages without updates or without a resolved latest version are skipped.
+*/
+declare function buildMigrationGuides(packages: readonly GuidePackageVersionInfo[], migrationsDir: string | null): MigrationGuide[];
+export { MigrationGuide, buildMigrationGuides, PrintUpgradeResultsOptions, printUpgradeResults, UpgradeOptions, PackageVersionInfo, CodemodSummary, UpgradeResult, runUpgrade, UpgradeReportStatus, UpgradeReportFlags, UpgradeReport, WriteUpgradeReportMeta, writeUpgradeReportSafely };

package/dist/shared/outfitter-5r6q2749.d.ts

@@ -0,0 +1,18 @@
+import { TargetCategory, TargetDefinition, TargetId, TargetScope, TargetStatus } from "./outfitter-58rn1sj1.js";
+import { NotFoundError, Result, ValidationError } from "@outfitter/contracts";
+declare const TARGET_REGISTRY: ReadonlyMap<TargetId, TargetDefinition>;
+declare const TARGET_IDS: readonly TargetId[];
+declare const READY_TARGET_IDS: readonly TargetId[];
+declare const INIT_TARGET_IDS: readonly TargetId[];
+declare const SCAFFOLD_TARGET_IDS: readonly TargetId[];
+declare function getTarget(id: string): Result<TargetDefinition, NotFoundError>;
+declare function getReadyTarget(id: string): Result<TargetDefinition, NotFoundError | ValidationError>;
+declare function getInitTarget(id: string): Result<TargetDefinition, NotFoundError | ValidationError>;
+declare function getScaffoldTarget(id: string): Result<TargetDefinition, NotFoundError | ValidationError>;
+declare function resolvePlacement(target: TargetDefinition): "apps" | "packages";
+declare function listTargets(filter?: {
+	readonly status?: TargetStatus;
+	readonly scope?: TargetScope;
+	readonly category?: TargetCategory;
+}): readonly TargetDefinition[];
+export { TARGET_REGISTRY, TARGET_IDS, READY_TARGET_IDS, INIT_TARGET_IDS, SCAFFOLD_TARGET_IDS, getTarget, getReadyTarget, getInitTarget, getScaffoldTarget, resolvePlacement, listTargets };

package/dist/shared/outfitter-5vx1bp7h.js

@@ -0,0 +1,41 @@
+// @bun
+// apps/outfitter/src/commands/jq-utils.ts
+async function applyJq(data, expr, options) {
+  try {
+    const json = JSON.stringify(data);
+    const args = ["jq", ...options?.compact ? ["-c"] : [], expr];
+    const proc = Bun.spawn(args, {
+      stdin: new Response(json),
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+    if (exitCode !== 0) {
+      process.stderr.write(`jq error: ${stderr.trim()}
+`);
+      return options?.compact ? `${JSON.stringify(data)}
+` : `${JSON.stringify(data, null, 2)}
+`;
+    }
+    return stdout;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "unknown jq execution error";
+    const missingBinary = /enoent|not found/i.test(message);
+    if (missingBinary) {
+      process.stderr.write(`jq is not installed. Install jq or omit --jq to continue.
+`);
+    } else {
+      process.stderr.write(`jq execution error: ${message}
+`);
+    }
+    return options?.compact ? `${JSON.stringify(data)}
+` : `${JSON.stringify(data, null, 2)}
+`;
+  }
+}
+
+export { applyJq };

package/dist/shared/outfitter-6ddf91vh.js

@@ -0,0 +1,190 @@
+// @bun
+import {
+  buildScaffoldPlan,
+  convertToWorkspace,
+  detectProjectStructure,
+  ensureWorkspacePattern,
+  validateScaffoldTargetName
+} from "./outfitter-qsd5638j.js";
+import {
+  getScaffoldTarget
+} from "./outfitter-g3hvjshg.js";
+import {
+  deriveProjectName,
+  executePlan,
+  isPathWithin
+} from "./outfitter-q1g58t85.js";
+import {
+  printScaffoldResults
+} from "./outfitter-qsrx7m4w.js";
+import {
+  runPostScaffold
+} from "./outfitter-4s9meh3j.js";
+import {
+  scaffoldWorkspaceRoot
+} from "./outfitter-1fy7byz5.js";
+import {
+  OperationCollector
+} from "./outfitter-1h7k8xxt.js";
+
+// apps/outfitter/src/commands/scaffold.ts
+import { existsSync } from "fs";
+import { basename, join, resolve } from "path";
+import { exitWithError } from "@outfitter/cli";
+import { Result } from "@outfitter/contracts";
+class ScaffoldCommandError extends Error {
+  _tag = "ScaffoldCommandError";
+  constructor(message) {
+    super(message);
+    this.name = "ScaffoldCommandError";
+  }
+}
+async function runScaffold(options) {
+  const targetResult = getScaffoldTarget(options.target);
+  if (targetResult.isErr()) {
+    return Result.err(new ScaffoldCommandError(targetResult.error.message));
+  }
+  const target = targetResult.value;
+  const targetName = deriveProjectName(options.name ?? target.id);
+  const targetNameValidation = validateScaffoldTargetName(targetName);
+  if (targetNameValidation.isErr()) {
+    return Result.err(new ScaffoldCommandError(targetNameValidation.error));
+  }
+  const dryRun = options.dryRun;
+  const collector = dryRun ? new OperationCollector : undefined;
+  const structureResult = detectProjectStructure(options.cwd);
+  if (structureResult.isErr()) {
+    return Result.err(new ScaffoldCommandError(structureResult.error));
+  }
+  let rootDir = resolve(options.cwd);
+  let converted = false;
+  let movedExisting;
+  let workspacePatternsUpdated = false;
+  if (structureResult.value.kind === "workspace") {
+    rootDir = structureResult.value.rootDir;
+    const patternResult = ensureWorkspacePattern(rootDir, target.placement, dryRun, collector);
+    if (patternResult.isErr()) {
+      return Result.err(new ScaffoldCommandError(patternResult.error));
+    }
+    workspacePatternsUpdated = patternResult.value;
+  } else if (structureResult.value.kind === "single-package") {
+    const conversionResult = convertToWorkspace(structureResult.value.rootDir, structureResult.value.packageJson, dryRun, collector);
+    if (conversionResult.isErr()) {
+      return Result.err(new ScaffoldCommandError(conversionResult.error));
+    }
+    rootDir = structureResult.value.rootDir;
+    converted = true;
+    movedExisting = conversionResult.value.movedExisting;
+  } else {
+    const workspaceName = `${basename(rootDir)}-workspace`;
+    if (dryRun) {
+      const packageJsonPath = join(rootDir, "package.json");
+      if (existsSync(packageJsonPath) && !options.force) {
+        return Result.err(new ScaffoldCommandError(`Directory '${rootDir}' already has a package.json. Use --force to overwrite.`));
+      }
+      collector?.add({
+        type: "dir-create",
+        path: join(rootDir, "apps")
+      });
+      collector?.add({
+        type: "dir-create",
+        path: join(rootDir, "packages")
+      });
+      collector?.add(existsSync(packageJsonPath) ? {
+        type: "file-overwrite",
+        path: packageJsonPath,
+        source: "generated"
+      } : {
+        type: "file-create",
+        path: packageJsonPath,
+        source: "generated"
+      });
+      const gitignorePath = join(rootDir, ".gitignore");
+      if (options.force || !existsSync(gitignorePath)) {
+        collector?.add(existsSync(gitignorePath) ? {
+          type: "file-overwrite",
+          path: gitignorePath,
+          source: "generated"
+        } : {
+          type: "file-create",
+          path: gitignorePath,
+          source: "generated"
+        });
+      }
+    } else {
+      const workspaceResult = scaffoldWorkspaceRoot(rootDir, workspaceName, options.force);
+      if (workspaceResult.isErr()) {
+        return Result.err(new ScaffoldCommandError(workspaceResult.error.message));
+      }
+    }
+    converted = true;
+  }
+  const targetBaseDir = resolve(rootDir, target.placement);
+  const targetDir = resolve(targetBaseDir, targetName);
+  if (!isPathWithin(targetBaseDir, targetDir)) {
+    return Result.err(new ScaffoldCommandError(`Invalid target name '${targetName}': path escapes '${targetBaseDir}'`));
+  }
+  if (existsSync(targetDir) && !options.force && !dryRun) {
+    return Result.err(new ScaffoldCommandError(`'${target.placement}/${targetName}/' already exists. Use --force to overwrite.`));
+  }
+  const plan = buildScaffoldPlan(target, rootDir, targetName, options);
+  const executeResult = await executePlan(plan, {
+    force: options.force,
+    ...collector ? { collector } : {}
+  });
+  if (executeResult.isErr()) {
+    return Result.err(new ScaffoldCommandError(executeResult.error.message));
+  }
+  const postScaffoldResult = await runPostScaffold({
+    rootDir,
+    projectDir: targetDir,
+    origin: "scaffold",
+    target: target.id,
+    structure: "workspace",
+    skipInstall: options.skipInstall,
+    skipGit: true,
+    skipCommit: true,
+    dryRun,
+    installTimeoutMs: options.installTimeout ?? 60000
+  }, collector);
+  if (postScaffoldResult.isErr()) {
+    return Result.err(new ScaffoldCommandError("Post-scaffold step failed"));
+  }
+  return Result.ok({
+    target: target.id,
+    rootDir,
+    targetDir,
+    converted,
+    movedExisting,
+    workspacePatternsUpdated,
+    blocksAdded: executeResult.value.blocksAdded,
+    postScaffold: postScaffoldResult.value,
+    ...collector ? { dryRunPlan: collector.toJSON() } : {}
+  });
+}
+function scaffoldCommand(program) {
+  program.command("scaffold <target> [name]").description("Add a capability to an existing project").option("-f, --force", "Overwrite existing files", false).option("--skip-install", "Skip bun install", false).option("--dry-run", "Preview changes without executing", false).option("--with <blocks>", "Comma-separated tooling blocks to add").option("--no-tooling", "Skip default tooling blocks").option("--local", "Use workspace:* for @outfitter dependencies").option("--install-timeout <ms>", "bun install timeout in ms").action(async (target, name, _flags, command) => {
+    const resolvedFlags = command.optsWithGlobals();
+    const mode = resolvedFlags.json ? "json" : undefined;
+    const outputOptions = mode ? { mode } : undefined;
+    const result = await runScaffold({
+      target,
+      name,
+      force: Boolean(resolvedFlags.force),
+      skipInstall: Boolean(resolvedFlags.skipInstall),
+      dryRun: Boolean(resolvedFlags.dryRun),
+      with: resolvedFlags.with,
+      noTooling: resolvedFlags.noTooling,
+      local: resolvedFlags.local,
+      cwd: process.cwd(),
+      ...resolvedFlags.installTimeout !== undefined ? { installTimeout: resolvedFlags.installTimeout } : {}
+    });
+    if (result.isErr()) {
+      exitWithError(result.error, outputOptions);
+      return;
+    }
+    await printScaffoldResults(result.value, outputOptions);
+  });
+}
+
+export { ScaffoldCommandError, runScaffold, scaffoldCommand };