@archora/forge-pro 2.0.0

package/LICENSE

@@ -0,0 +1,113 @@
+Archora Forge Intelligence Proprietary Source-Available License (Paid-Use-Only)
+
+Copyright (c) 2026 Aleksandr Kotov (the "Licensor"). All rights reserved.
+
+This license governs the @archora/forge-pro package — "Forge Intelligence",
+the commercial team/CI layer of Archora Forge (the "Software"). The free
+Archora Forge generator packages are licensed separately under the MIT License
+(see the LICENSE file at the root of this repository) and are not subject to
+the terms below.
+
+The source code and any other materials of the Software are proprietary and
+confidential to the Licensor. They are published in source-available form for
+the sole purpose of allowing prospective licensees to inspect and evaluate the
+Software before purchasing a commercial license.
+
+This Software is NOT open source. The publication of this repository on a
+public hosting platform does NOT constitute a grant of any open-source or
+free-software license, and does NOT grant any rights beyond those expressly
+stated below.
+
+1. Limited Permission Granted Without a Paid License
+
+   Without entering into a separate written commercial license with the
+   Licensor, you are permitted to do ONLY the following with the Software:
+
+   (a) view and read the source code via the hosting platform on which
+       it is published;
+   (b) clone or download a copy strictly for the purpose of personally
+       evaluating whether to obtain a paid commercial license, for a
+       reasonable evaluation period not exceeding thirty (30) days; and
+   (c) discuss the Software publicly (e.g. cite, link, or quote short
+       excerpts for commentary, criticism, news reporting, teaching,
+       scholarship, or research) consistent with applicable fair use
+       or fair dealing law.
+
+   No other rights are granted. In particular, and without limitation,
+   the following are NOT permitted without a separate paid commercial
+   license signed by the Licensor:
+
+   - any use of the Software, in whole or in part, in any project,
+     product, service, library, internal tool, script, pipeline,
+     build, CI job, or deliverable, whether commercial or
+     non-commercial, paid or unpaid, personal or organizational,
+     for-profit or not-for-profit, including hobby and educational
+     projects;
+   - execution of the Software for any purpose other than short-term
+     evaluation by you personally as described in clause 1(b);
+   - copying, modifying, merging, publishing, sublicensing,
+     distributing, selling, hosting, or offering the Software (or any
+     derivative work) as a service to any third party;
+   - removing or altering any copyright, trademark, license, or
+     attribution notices contained in the Software or in its outputs;
+   - using the Software, its source code, or its outputs to train,
+     fine-tune, evaluate, benchmark, or otherwise develop
+     machine-learning or artificial-intelligence models, datasets, or
+     systems;
+   - reverse-engineering the Software for any purpose other than
+     evaluation as described in clause 1(b), to the extent such
+     restriction is permitted by applicable law.
+
+2. No Implied License
+
+   No license is granted by implication, estoppel, exhaustion, course of
+   dealing, or otherwise. Public availability of this repository does
+   not change this.
+
+3. Commercial License Required
+
+   To use the Software for any purpose beyond the limited evaluation
+   described in Section 1, you must first obtain a paid commercial
+   license from the Licensor. Pricing and terms are available on
+   request — see COMMERCIAL-LICENSE.md at the root of this repository.
+
+4. Trademarks
+
+   "Archora" and "Archora Forge" and any associated names, logos, and
+   brands are trademarks of the Licensor. No trademark rights are
+   granted by this license. Forks, modifications, or derivative works
+   (where permitted under a separate commercial license) may not use
+   these marks without the Licensor's prior written consent.
+
+5. Term and Termination
+
+   Your permission under Section 1 terminates automatically and
+   immediately upon any breach of this license, or upon written notice
+   from the Licensor. Upon termination you must delete all copies of
+   the Software in your possession or control, except for archival
+   copies you are required by law to retain.
+
+6. No Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   THE LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR IN CONNECTION
+   WITH THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY
+   OF SUCH DAMAGES.
+
+8. Governing Law
+
+   This license shall be governed by and construed in accordance with
+   the laws applicable at the Licensor's place of residence, without
+   regard to its conflict-of-laws principles.
+
+For commercial licensing inquiries, contact:
+  Email:    akotov@archora.dev
+  Telegram: @akotofff

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { CAC } from 'cac';
+
+/**
+ * Forge Intelligence (Pro) command tier.
+ *
+ * Everything registered here is the paid, team/CI layer that operates on top
+ * of the free generator: impact reporting, the CI readiness gate, adoption
+ * audits and pilot reporting. These commands are license-gated at runtime via
+ * `requireCommercialLicense` inside each command action.
+ *
+ * This module is the single extraction seam: moving it (and the command files
+ * it imports) into a standalone `@archora/forge-pro` package later requires no
+ * changes to the free CLI other than swapping this import for a dynamic load.
+ */
+declare function registerProCommands(cli: CAC): void;
+
+export { registerProCommands };

package/dist/index.js

@@ -0,0 +1,826 @@
+// src/commands/audit.command.ts
+import {
+  logger,
+  requireCommercialLicense,
+  runAuditPackage
+} from "@archora/forge-cli/internal";
+function registerAuditCommand(cli) {
+  cli.command("audit [schema]", "Create a local frontend API adoption package").option("--config <path>", "Use a specific Archora Forge config file").option(
+    "--schema-header <header>",
+    'Add a remote schema request header as "name:value" or "name=value"'
+  ).option("--out <path>", "Output directory for the audit package").option("--json", "Print the audit JSON payload").option("--skip-typecheck", "Skip generated-output TypeScript typecheck").option("--min-health-score <score>", "Use this health score as the audit acceptance threshold").action(async (schema, options) => {
+    try {
+      await requireCommercialLicense("audit");
+      const result = await runAuditPackage(schema, options);
+      if (options.json) {
+        console.log(JSON.stringify(result.payload, null, 2));
+      } else {
+        logger.title();
+        logger.line(`Audit package: ${result.outDir}`);
+        logger.line(`Schemas: ${result.entries.length}`);
+        logger.line(`Resources: ${result.payload.resources}`);
+        logger.line(`Generated files: ${result.payload.generatedFiles}`);
+        logger.line(`Typecheck: ${result.payload.typecheck.status}`);
+        logger.line(`Decision: ${result.payload.readiness.decision}`);
+      }
+      process.exitCode = result.payload.ok ? 0 : 1;
+    } catch (error) {
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            { ok: false, error: error instanceof Error ? error.message : String(error) },
+            null,
+            2
+          )
+        );
+      } else {
+        logger.error(error instanceof Error ? error.message : String(error));
+      }
+      process.exitCode = 2;
+    }
+  });
+}
+
+// src/commands/check.command.ts
+import {
+  calculateSchemaHealth,
+  calculateDrift,
+  collectDiagnostics,
+  createGenerationPlan,
+  createSchemaCoverageMatrix,
+  detectResources,
+  mergeSchemaCoverageMatrices,
+  normalizeOpenApi,
+  parseOpenApi,
+  summarizeGeneratorMetadata,
+  summarizeFilePlan
+} from "@archora/forge-core";
+import { resolveQueryComposables } from "@archora/forge-adapters";
+import { loadCliConfigSet, createHtmlReport, requireCommercialLicense as requireCommercialLicense2, writeReportFile, logger as logger2 } from "@archora/forge-cli/internal";
+function registerCheckCommand(cli) {
+  cli.command("check [schema]", "Check generated output drift and diagnostics without writing files").option("--config <path>", "Use a specific Archora Forge config file").option("--schema-header <header>", 'Add a remote schema request header as "name:value" or "name=value"').option("--json", "Print machine-readable JSON").option("--report <format>", "Print a report format: json, markdown or html").option("--report-file <path>", "Write the selected check report to a file").option("--min-health-score <score>", "Fail when the OpenAPI health score is below this value").action(async (schema, options) => {
+    try {
+      await requireCommercialLicense2("check");
+      assertReportFormat(options.report);
+      const minHealthScore = parseMinHealthScore(options.minHealthScore);
+      const checks = await Promise.all((await loadCliConfigSet(schema, options)).map((loaded) => runCheck(loaded, { minHealthScore })));
+      const primary = checks[0];
+      if (!primary) throw new Error("No OpenAPI schema inputs were resolved.");
+      const drift = checks.flatMap((check) => check.drift);
+      const diagnostics = checks.flatMap((check) => check.diagnostics);
+      const failedChecks = [...new Set(checks.flatMap((check) => check.failedChecks))];
+      const generator = summarizeCheckGeneratorMetadata(checks.map((check) => check.generator));
+      const coverage = mergeSchemaCoverageMatrices(checks.map((check) => check.coverage));
+      const ok = failedChecks.length === 0;
+      const healthScore = Math.min(...checks.map((check) => check.healthScore));
+      const summary = {
+        healthScore,
+        resources: checks.reduce((total, check) => total + check.resources, 0),
+        generatedFiles: checks.reduce((total, check) => total + check.generatedFiles, 0),
+        protectedFiles: checks.reduce((total, check) => total + check.protectedFiles, 0),
+        diagnostics: diagnostics.length,
+        drift: drift.length,
+        failedChecks: failedChecks.length
+      };
+      const payload = {
+        ok,
+        schema: primary.schema,
+        schemas: checks.map((check) => ({
+          name: check.name,
+          schema: check.schema,
+          configPath: check.configPath,
+          healthScore: check.healthScore,
+          resources: check.resources,
+          generatedFiles: check.generatedFiles,
+          protectedFiles: check.protectedFiles,
+          driftCount: check.drift.length,
+          diagnosticsCount: check.diagnostics.length,
+          failedChecks: check.failedChecks,
+          generator: check.generator,
+          coverage: check.coverage
+        })),
+        healthScore,
+        resources: summary.resources,
+        generatedFiles: summary.generatedFiles,
+        protectedFiles: summary.protectedFiles,
+        failedChecks,
+        generator,
+        coverage,
+        readiness: createReadinessSummary({ summary, failedChecks, drift, diagnostics }),
+        drift,
+        diagnostics
+      };
+      if (options.reportFile) {
+        const reportPath = await writeReportFile(
+          options.reportFile,
+          createCheckReport(payload, options)
+        );
+        console.log(`Report written: ${reportPath}`);
+      } else if (options.json || options.report === "json") {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (options.report === "markdown") {
+        console.log(createMarkdownReport(payload));
+      } else if (options.report === "html") {
+        console.log(createHtmlReport("Archora Forge Check", payload));
+      } else {
+        logger2.title();
+        logger2.line(checks.length === 1 ? `Schema: ${primary.schema}` : `Schemas: ${checks.length}`);
+        logger2.line(`Resources: ${payload.resources}`);
+        logger2.line(`Generated files: ${payload.generatedFiles}`);
+        logger2.line(`Protected files: ${payload.protectedFiles}`);
+        logger2.line(`Failed checks: ${payload.failedChecks.length > 0 ? payload.failedChecks.join(", ") : "none"}`);
+        logger2.line("");
+        logger2.line("Drift:");
+        if (drift.length === 0) logger2.success("Generated output is up to date.");
+        for (const entry of drift) logger2.warn(`${entry.path} is ${entry.kind}`);
+        logger2.line("");
+        logger2.line("Diagnostics:");
+        if (diagnostics.length === 0) logger2.success("No diagnostics.");
+        for (const diagnostic of diagnostics.slice(0, 20)) logger2.warn(`${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`);
+        logger2.line("");
+        logger2.line(ok ? "Result: generated output is up to date." : "Result: generated output is not up to date.");
+      }
+      process.exitCode = ok ? 0 : 1;
+    } catch (error) {
+      if (options.json) {
+        console.log(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2));
+      } else {
+        logger2.error(error instanceof Error ? error.message : String(error));
+      }
+      process.exitCode = 2;
+    }
+  });
+}
+function assertReportFormat(report) {
+  if (report !== void 0 && report !== "json" && report !== "markdown" && report !== "html") {
+    throw new Error(`Invalid report format "${report}". Expected "json", "markdown" or "html".`);
+  }
+}
+function createCheckReport(payload, options) {
+  if (options.report === "html") return createHtmlReport("Archora Forge Check", payload);
+  if (options.json || options.report === "json") return JSON.stringify(payload, null, 2);
+  return createMarkdownReport(payload);
+}
+function parseMinHealthScore(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 100) {
+    throw new Error(`Invalid minimum health score "${value}". Expected a number between 0 and 100.`);
+  }
+  return parsed;
+}
+async function runCheck(loaded, options = {}) {
+  const document = await parseOpenApi(loaded.schema, loaded.config.schemaRequest);
+  const normalized = normalizeOpenApi(document);
+  const resources = detectResources(normalized.operations).filter((resource) => loaded.config.resources[resource.name]?.enabled !== false);
+  const plan = await createGenerationPlan({ config: loaded.config, normalized, resources, cwd: loaded.cwd, composables: resolveQueryComposables(loaded.config.target.query) });
+  const summary = summarizeFilePlan(plan.files);
+  const drift = await calculateDrift(plan.files, { cwd: loaded.cwd });
+  const generator = await summarizeGeneratorMetadata(plan.files, { cwd: loaded.cwd });
+  const diagnostics = collectDiagnostics(normalized);
+  const coverage = createSchemaCoverageMatrix(normalized, diagnostics);
+  const healthScore = calculateSchemaHealth(normalized).score;
+  const failedChecks = evaluateFailedChecks({
+    drift,
+    diagnostics,
+    healthScore,
+    ci: { ...loaded.config.ci, minHealthScore: options.minHealthScore ?? loaded.config.ci.minHealthScore }
+  });
+  return {
+    name: loaded.name ?? "default",
+    schema: loaded.schema,
+    configPath: loaded.configPath,
+    healthScore,
+    resources: resources.length,
+    generatedFiles: plan.files.filter((file) => file.kind === "generated").length,
+    protectedFiles: summary.protected,
+    generator,
+    coverage,
+    drift,
+    diagnostics,
+    failedChecks
+  };
+}
+function createMarkdownReport(payload) {
+  const drift = payload.drift.length === 0 ? "- No drift detected." : payload.drift.map((entry) => `- \`${entry.path}\` is ${entry.kind}`).join("\n");
+  const diagnostics = payload.diagnostics.length === 0 ? "- No diagnostics." : payload.diagnostics.map((diagnostic) => `- ${diagnostic.severity} \`${diagnostic.code}\`: ${diagnostic.message}`).join("\n");
+  const readiness = payload.readiness ? `## Pilot Readiness
+
+Readiness: ${payload.readiness.status}
+
+${payload.readiness.gate ? `Gate: ${payload.readiness.gate.result}
+
+Recommended CI mode: ${payload.readiness.gate.recommendedCiMode}
+
+Gate reason: ${payload.readiness.gate.reason}
+` : ""}
+
+Decision: ${payload.readiness.decision}
+
+Blockers:
+${formatMarkdownList(payload.readiness.blockers, "No blockers.")}
+
+Warnings:
+${formatMarkdownList(payload.readiness.warnings, "No warnings.")}
+
+Next actions:
+${formatMarkdownList(payload.readiness.nextActions, "No action required.")}
+
+` : "";
+  const generator = payload.generator ? formatGeneratorMarkdown(payload.generator) : "";
+  return `# Archora Forge Check
+
+Status: ${payload.ok ? "passed" : "failed"}
+
+Failed checks: ${payload.failedChecks.length > 0 ? payload.failedChecks.join(", ") : "none"}
+
+Health score: ${payload.healthScore ?? "n/a"}
+
+${readiness}
+${generator}
+## Drift
+
+${drift}
+
+## Diagnostics
+
+${diagnostics}
+
+## Suggested action
+
+${payload.ok ? "No action required." : "Run `archora-forge generate <schema>` and commit generated changes, or fix reported OpenAPI diagnostics."}
+`;
+}
+function summarizeCheckGeneratorMetadata(summaries) {
+  const files = {
+    total: summaries.reduce((total, summary) => total + summary.files.total, 0),
+    missingMetadata: summaries.flatMap((summary) => summary.files.missingMetadata),
+    versionMismatches: summaries.flatMap((summary) => summary.files.versionMismatches),
+    schemaHashMismatches: summaries.flatMap((summary) => summary.files.schemaHashMismatches),
+    configHashMismatches: summaries.flatMap((summary) => summary.files.configHashMismatches)
+  };
+  const mismatchCount = files.versionMismatches.length + files.schemaHashMismatches.length + files.configHashMismatches.length;
+  return {
+    status: mismatchCount > 0 ? "mismatch" : files.missingMetadata.length > 0 ? "missing-metadata" : "current",
+    version: summaries[0]?.version ?? "unknown",
+    files
+  };
+}
+function formatGeneratorMarkdown(summary) {
+  return `## Generator
+
+Status: ${summary.status}
+
+Version: ${summary.version}
+
+Generated files: ${summary.files.total}
+
+Missing metadata: ${summary.files.missingMetadata.length}
+
+Version mismatches: ${summary.files.versionMismatches.length}
+
+Schema hash mismatches: ${summary.files.schemaHashMismatches.length}
+
+Config hash mismatches: ${summary.files.configHashMismatches.length}
+
+`;
+}
+function formatMarkdownList(items, empty) {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : `- ${empty}`;
+}
+function createReadinessSummary(input) {
+  const blockers = [
+    ...input.failedChecks.map((check) => `Failed check: ${check}.`),
+    ...input.drift.length > 0 ? ["Generated output drift is present."] : [],
+    ...input.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => `Error diagnostic: ${diagnostic.code}.`)
+  ];
+  const warningDiagnostics = input.diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+  const warnings = [
+    ...warningDiagnostics.length > 0 ? [`${warningDiagnostics.length} warning diagnostic${warningDiagnostics.length === 1 ? "" : "s"} need review.`] : [],
+    ...input.summary.healthScore < 90 ? [`Health score is ${input.summary.healthScore}, below the recommended pilot threshold of 90.`] : []
+  ];
+  const status = blockers.length > 0 ? "blocked" : warnings.length > 0 ? "needs-attention" : "ready";
+  const gate = status === "ready" ? {
+    result: "pass",
+    recommendedCiMode: "block",
+    reason: "Keep the blocking check enabled; no report findings require human acceptance."
+  } : status === "needs-attention" ? {
+    result: "warn",
+    recommendedCiMode: "comment",
+    reason: "Use comment-only mode until warnings are triaged or accepted."
+  } : {
+    result: "fail",
+    recommendedCiMode: "block",
+    reason: "Block merge or require explicit acceptance before pilot handoff."
+  };
+  const nextActions = status === "ready" ? ["Use the report as the pilot readiness artifact and keep `archora-forge check` in CI."] : [
+    ...input.drift.length > 0 ? ["Run `archora-forge generate` and commit the generated output, or review intentional drift before the pilot handoff."] : [],
+    ...input.diagnostics.length > 0 ? ["Review diagnostics and decide which schema fixes are required for the pilot scope."] : [],
+    ...input.summary.healthScore < 90 ? ["Improve schema health before using the report as a go/no-go artifact."] : []
+  ];
+  return {
+    status,
+    gate,
+    decision: status === "ready" ? "Schema is ready for a pilot readiness handoff under the current check policy." : status === "needs-attention" ? "Schema can continue through pilot review, but findings should be triaged first." : "Schema is not ready for pilot handoff until blockers are resolved or explicitly accepted.",
+    blockers,
+    warnings,
+    nextActions: nextActions.length > 0 ? nextActions : ["Review failed checks and diagnostics before the pilot handoff."],
+    summary: input.summary
+  };
+}
+function evaluateFailedChecks(input) {
+  const failed = /* @__PURE__ */ new Set();
+  if (input.ci.failOnDrift && input.drift.length > 0) failed.add("drift");
+  if (input.ci.minHealthScore !== void 0 && input.healthScore < input.ci.minHealthScore) failed.add("health-score");
+  if (input.diagnostics.some((diagnostic) => diagnostic.severity === "error")) failed.add("errors");
+  if (input.ci.failOnWarnings && input.diagnostics.some((diagnostic) => diagnostic.severity === "warning")) failed.add("warnings");
+  if (input.ci.failOnUnsupportedFeatures && input.diagnostics.some((diagnostic) => diagnostic.code.startsWith("unsupported-"))) {
+    failed.add("unsupported-features");
+  }
+  if (input.ci.failOnMissingSchemas && input.diagnostics.some((diagnostic) => diagnostic.code === "missing-request-schema" || diagnostic.code === "missing-response-schema")) {
+    failed.add("missing-schemas");
+  }
+  return [...failed];
+}
+
+// src/commands/ci.command.ts
+import { readFile } from "fs/promises";
+import { requireCommercialLicense as requireCommercialLicense3, writeReportFile as writeReportFile2, logger as logger3 } from "@archora/forge-cli/internal";
+var PROVIDERS = {
+  github: {
+    workflowPath: ".github/workflows/archora-forge-impact.yml",
+    build: createGithubWorkflow
+  },
+  gitlab: {
+    workflowPath: ".gitlab/archora-forge-impact.yml",
+    build: createGitlabWorkflow
+  }
+};
+function registerCiCommand(cli) {
+  cli.command("ci <action> <provider>", "Scaffold a turnkey CI kit for Forge impact review").option("--force", "Overwrite an existing workflow file when its content differs").option("--output <path>", "Write the workflow to a custom path").option("--mode <mode>", "Workflow mode: impact or pilot").option("--gate <mode>", "Merge gate mode: block or comment").option("--schema <path>", "OpenAPI schema path inside the repository").option("--base <ref>", "Git base ref for the previous schema").option("--no-readme", "Skip writing the FORGE_CI.md handoff document").action(async (action, provider, options) => {
+    await requireCommercialLicense3("ci");
+    if (action !== "init") throw new Error(`Unknown CI action "${action}". Use init.`);
+    if (!isProvider(provider)) {
+      throw new Error(`Unsupported CI provider "${provider}". Use github or gitlab.`);
+    }
+    const config = {
+      mode: normalizeMode(options.mode),
+      gate: normalizeGate(options.gate),
+      schema: options.schema ?? "openapi.yaml",
+      base: options.base ?? "origin/main"
+    };
+    const target = PROVIDERS[provider];
+    const workflowPath = options.output ?? target.workflowPath;
+    const workflowResult = await writeManaged(workflowPath, target.build(config), options.force);
+    reportWrite(workflowPath, workflowResult);
+    if (options.readme !== false) {
+      const readmeResult = await writeManaged(
+        "FORGE_CI.md",
+        createHandoff(provider, config, workflowPath),
+        options.force
+      );
+      reportWrite("FORGE_CI.md", readmeResult);
+    }
+    logger3.line(
+      provider === "gitlab" ? `Next: add \`include: { local: '${workflowPath}' }\` to your .gitlab-ci.yml.` : `Next: review OPENAPI_SCHEMA and OPENAPI_BASE_REF in ${workflowPath}.`
+    );
+  });
+}
+async function writeManaged(path, content, force) {
+  const existing = await readFile(path, "utf8").catch(() => null);
+  if (existing === null) {
+    await writeReportFile2(path, content);
+    return "created";
+  }
+  if (existing === content) return "unchanged";
+  if (!force) return "skipped";
+  await writeReportFile2(path, content);
+  return "updated";
+}
+function reportWrite(path, result) {
+  if (result === "created") logger3.success(`Created ${path}`);
+  else if (result === "updated") logger3.success(`Updated ${path}`);
+  else if (result === "unchanged") logger3.line(`${path} is already up to date`);
+  else {
+    logger3.warn(`${path} already exists with different content`);
+    logger3.line("Re-run with --force to overwrite it.");
+  }
+}
+function isProvider(value) {
+  return value === "github" || value === "gitlab";
+}
+function normalizeMode(value) {
+  if (!value) return "impact";
+  if (value === "impact" || value === "pilot") return value;
+  throw new Error("Invalid CI mode. Use impact or pilot.");
+}
+function normalizeGate(value) {
+  if (!value) return "block";
+  if (value === "block" || value === "comment") return value;
+  throw new Error("Invalid CI gate mode. Use block or comment.");
+}
+function createGithubWorkflow(config) {
+  const runStep = config.mode === "pilot" ? `          pnpm exec archora-forge pilot "$OPENAPI_SCHEMA" --base "$OPENAPI_BASE_REF" \\
+            --repo . \\
+            --out forge-pilot \\
+            --skip-typecheck` : `          pnpm exec archora-forge impact "$OPENAPI_SCHEMA" --base "$OPENAPI_BASE_REF" \\
+            --repo . \\
+            --report markdown \\
+            --report-file forge-impact.md \\
+            --pr-comment-file forge-impact-pr.md`;
+  const artifactPath = config.mode === "pilot" ? `            forge-pilot/**` : `            forge-impact.md
+            forge-impact-pr.md`;
+  const blockStep = config.gate === "block" ? `
+      - name: Block merge on blocked API impact
+        if: steps.forge.outcome == 'failure'
+        run: |
+          echo "Archora Forge reported blocked API impact. Review the PR comment and uploaded artifacts."
+          exit 1` : "";
+  return `name: archora-forge-impact
+
+on:
+  pull_request:
+    paths:
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.json'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  OPENAPI_SCHEMA: ${config.schema}
+  OPENAPI_BASE_REF: ${config.base}
+  FORGE_GATE_MODE: ${config.gate}
+
+jobs:
+  ${config.mode}:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Run Forge impact
+        id: forge
+        continue-on-error: true
+        run: |
+${runStep}
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: archora-forge-impact
+          path: |
+${artifactPath}
+
+      - uses: thollander/actions-comment-pull-request@v3
+        if: always() && env.OPENAPI_SCHEMA != '' && hashFiles('forge-impact-pr.md') != ''
+        with:
+          file-path: forge-impact-pr.md
+          comment-tag: archora-forge-impact
+${blockStep}
+`;
+}
+function createGitlabWorkflow(config) {
+  const runCommand = config.mode === "pilot" ? `pnpm exec archora-forge pilot "$OPENAPI_SCHEMA" --base "$OPENAPI_BASE_REF" --repo . --out forge-pilot --skip-typecheck` : `pnpm exec archora-forge impact "$OPENAPI_SCHEMA" --base "$OPENAPI_BASE_REF" --repo . --report markdown --report-file forge-impact.md --pr-comment-file forge-impact-pr.md`;
+  const script = config.gate === "comment" ? `${runCommand} || true` : runCommand;
+  const artifacts = config.mode === "pilot" ? `      - forge-pilot/` : `      - forge-impact.md
+      - forge-impact-pr.md`;
+  return `# Include this file from your .gitlab-ci.yml:
+#   include:
+#     - local: '${PROVIDERS.gitlab.workflowPath}'
+
+archora-forge-impact:
+  stage: test
+  image: node:22
+  variables:
+    OPENAPI_SCHEMA: ${config.schema}
+    OPENAPI_BASE_REF: ${config.base}
+    FORGE_GATE_MODE: ${config.gate}
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  before_script:
+    - corepack enable
+    - corepack prepare pnpm@9.15.4 --activate
+    - git fetch origin "$OPENAPI_BASE_REF" || true
+    - pnpm install --frozen-lockfile
+  script:
+    - ${script}
+  artifacts:
+    when: always
+    expire_in: 1 week
+    paths:
+${artifacts}
+`;
+}
+function createHandoff(provider, config, workflowPath) {
+  const gateLine = config.gate === "block" ? "The pipeline **blocks the merge** when Forge reports a blocked frontend API change." : "The pipeline stays green and posts the impact report as a **comment/artifact** for reviewers.";
+  const unblock = config.gate === "block" ? `## Temporarily unblock a merge
+
+Set the gate to advisory and re-run \`archora-forge ci init ${provider} --gate comment --force\`,
+or resolve the blocking change and push again.` : "";
+  return `# Forge CI Kit
+
+This repository runs Archora Forge in CI to review OpenAPI changes before they break frontend code.
+
+- Provider: ${provider}
+- Workflow: \`${workflowPath}\`
+- Mode: ${config.mode}
+- Gate: ${config.gate}
+- Schema: \`${config.schema}\`
+- Base ref: \`${config.base}\`
+
+## What it does
+
+On every ${provider === "gitlab" ? "merge request" : "pull request"}, Forge compares the new OpenAPI
+schema against \`${config.base}\` and reports the frontend impact: breaking changes, affected
+generated files and a migration summary. ${gateLine}
+
+## How to read it
+
+- Open the \`archora-forge-impact\` artifact (\`forge-impact.md\`) for the full report.
+- ${provider === "gitlab" ? "Review the impact artifact attached to the pipeline." : "Read the `forge-impact-pr.md` comment posted on the PR."}
+- A blocked decision means a breaking frontend contract change needs handling before merge.
+
+${unblock}
+To change schema path, base ref, mode or gate, re-run \`archora-forge ci init ${provider}\` with
+the matching flags (add \`--force\` to overwrite).
+`;
+}
+
+// src/commands/contract-diff.command.ts
+import { diffOpenApiContracts, normalizeOpenApi as normalizeOpenApi2, parseOpenApi as parseOpenApi2 } from "@archora/forge-core";
+import { createHtmlReport as createHtmlReport2, readGitBaseSchema, formatImpactReport, formatPullRequestComment, scanSourceUsages, requireCommercialLicense as requireCommercialLicense4, writeReportFile as writeReportFile3, parseSchemaRequestHeaders, logger as logger4 } from "@archora/forge-cli/internal";
+function registerContractDiffCommand(cli) {
+  cli.command("contract-diff <oldSchema> <newSchema>", "Compare two OpenAPI schemas and report frontend impact").option("--schema-header <header>", 'Add a remote schema request header as "name:value" or "name=value"').option("--json", "Print machine-readable JSON").option("--report <format>", "Print a report format: json or html").option("--report-file <path>", "Write the selected contract diff report to a file").action(async (oldSchema, newSchema, options) => {
+    assertReportFormat2(options.report);
+    const schemaRequest = { headers: parseSchemaRequestHeaders(options.schemaHeader) };
+    const oldDocument = await parseOpenApi2(oldSchema, schemaRequest);
+    const newDocument = await parseOpenApi2(newSchema, schemaRequest);
+    const report = diffOpenApiContracts(normalizeOpenApi2(oldDocument), normalizeOpenApi2(newDocument));
+    const ok = !report.changes.some((change) => change.severity === "breaking");
+    const payload = { ok, oldSchema, newSchema, ...report };
+    if (options.reportFile) {
+      const reportPath = await writeReportFile3(options.reportFile, options.report === "html" ? createHtmlReport2("Archora Forge Contract Diff", payload) : JSON.stringify(payload, null, 2));
+      console.log(`Report written: ${reportPath}`);
+    } else if (options.json || options.report === "json") {
+      console.log(JSON.stringify(payload, null, 2));
+    } else if (options.report === "html") {
+      console.log(createHtmlReport2("Archora Forge Contract Diff", payload));
+    } else {
+      logger4.title();
+      logger4.line(`Old schema: ${oldSchema}`);
+      logger4.line(`New schema: ${newSchema}`);
+      logger4.line(`Changes: ${report.changes.length}`);
+      logger4.line(`Affected resources: ${report.affectedResources.length > 0 ? report.affectedResources.join(", ") : "none"}`);
+      logger4.line("");
+      for (const change of report.changes.slice(0, 40)) {
+        const line = `${change.severity} ${change.code}: ${change.message} (${change.location})`;
+        if (change.severity === "breaking") logger4.warn(line);
+        else logger4.line(line);
+      }
+    }
+    process.exitCode = ok ? 0 : 1;
+  });
+  cli.command("impact <schema> [newSchema]", "Create a frontend API impact report for a contract change").option("--schema-header <header>", 'Add a remote schema request header as "name:value" or "name=value"').option("--base <ref>", "Read the previous schema from this git ref").option("--json", "Print machine-readable JSON").option("--report <format>", "Print a report format: json, markdown or html").option("--report-file <path>", "Write the selected impact report to a file").option("--repo <path>", "Scan a frontend repository for impacted generated API usages").option("--pr-comment-file <path>", "Write a pull-request comment Markdown artifact").action(async (schema, newSchema, options) => {
+    await requireCommercialLicense4("impact");
+    assertImpactReportFormat(options.report);
+    const schemaRequest = { headers: parseSchemaRequestHeaders(options.schemaHeader) };
+    if (options.base && newSchema) throw new Error("Use either impact <oldSchema> <newSchema> or impact <schema> --base <ref>, not both.");
+    if (!options.base && !newSchema) throw new Error("Missing <newSchema>. Use impact <oldSchema> <newSchema> or impact <schema> --base <ref>.");
+    const baseSchema = options.base ? await readGitBaseSchema(schema, { base: options.base, repo: options.repo }) : null;
+    try {
+      const oldSchema = baseSchema?.path ?? schema;
+      const currentSchema = baseSchema ? schema : newSchema;
+      const oldDocument = await parseOpenApi2(oldSchema, schemaRequest);
+      const newDocument = await parseOpenApi2(currentSchema, schemaRequest);
+      const report = diffOpenApiContracts(normalizeOpenApi2(oldDocument), normalizeOpenApi2(newDocument));
+      const ok = report.decision.status !== "blocked";
+      const sourceUsages = options.repo ? await scanSourceUsages(options.repo, report) : [];
+      const payload = {
+        ok,
+        ...baseSchema ? { base: baseSchema.base } : {},
+        oldSchema: baseSchema?.label ?? oldSchema,
+        newSchema: currentSchema,
+        sourceUsages,
+        ...report
+      };
+      const reportFormat = options.json ? "json" : options.report ?? "markdown";
+      if (options.reportFile) {
+        const reportPath = await writeReportFile3(options.reportFile, formatImpactReport(reportFormat, payload));
+        console.log(`Report written: ${reportPath}`);
+      } else if (reportFormat === "json") {
+        console.log(JSON.stringify(payload, null, 2));
+      } else if (reportFormat === "html") {
+        console.log(createHtmlReport2("Frontend Impact Center", payload));
+      } else {
+        console.log(formatImpactReport("markdown", payload));
+      }
+      if (options.prCommentFile) {
+        const commentPath = await writeReportFile3(options.prCommentFile, formatPullRequestComment(payload));
+        console.log(`PR comment written: ${commentPath}`);
+      }
+      process.exitCode = ok ? 0 : 1;
+    } finally {
+      await baseSchema?.cleanup();
+    }
+  });
+}
+function assertReportFormat2(report) {
+  if (report !== void 0 && report !== "json" && report !== "html") {
+    throw new Error(`Invalid report format "${report}". Expected "json" or "html".`);
+  }
+}
+function assertImpactReportFormat(report) {
+  if (report !== void 0 && report !== "json" && report !== "markdown" && report !== "html") {
+    throw new Error(`Invalid report format "${report}". Expected "json", "markdown" or "html".`);
+  }
+}
+
+// src/commands/pilot.command.ts
+import { mkdir } from "fs/promises";
+import { join, resolve } from "path";
+import { diffOpenApiContracts as diffOpenApiContracts2, normalizeOpenApi as normalizeOpenApi3, parseOpenApi as parseOpenApi3 } from "@archora/forge-core";
+import { readGitBaseSchema as readGitBaseSchema2, formatImpactReport as formatImpactReport2, formatPullRequestComment as formatPullRequestComment2, scanSourceUsages as scanSourceUsages2, requireCommercialLicense as requireCommercialLicense5, writeReportFile as writeReportFile4, parseSchemaRequestHeaders as parseSchemaRequestHeaders2, logger as logger5, runAuditPackage as runAuditPackage2 } from "@archora/forge-cli/internal";
+function registerPilotCommand(cli) {
+  cli.command("pilot <schema>", "Create a paid-pilot package with impact, audit and go/no-go artifacts").option("--old <schema>", "Previous OpenAPI schema for impact review").option("--base <ref>", "Read the previous schema from this git ref").option("--repo <path>", "Scan a frontend repository for impacted generated API usages").option("--out <path>", "Output directory for the pilot package").option("--schema-header <header>", 'Add a remote schema request header as "name:value" or "name=value"').option("--skip-typecheck", "Skip generated-output TypeScript typecheck").option("--min-health-score <score>", "Use this health score as the audit acceptance threshold").action(async (schema, options) => {
+    try {
+      await requireCommercialLicense5("pilot");
+      if (!options.old && !options.base) throw new Error("Missing --old <schema> or --base <ref>. Pilot packages need a previous schema for impact review.");
+      if (options.old && options.base) throw new Error("Use either --old <schema> or --base <ref>, not both.");
+      const outDir = resolve(options.out ?? "forge-pilot");
+      await mkdir(outDir, { recursive: true });
+      const impact = await createPilotImpact(schema, options);
+      await Promise.all([
+        writeReportFile4(join(outDir, "impact.md"), formatImpactReport2("markdown", impact)),
+        writeReportFile4(join(outDir, "impact.json"), JSON.stringify(impact, null, 2)),
+        writeReportFile4(join(outDir, "impact-pr.md"), formatPullRequestComment2(impact))
+      ]);
+      const audit = await runAuditPackage2(schema, {
+        config: void 0,
+        out: join(outDir, "audit"),
+        json: false,
+        skipTypecheck: options.skipTypecheck,
+        minHealthScore: options.minHealthScore,
+        schemaHeader: options.schemaHeader
+      });
+      const decision = createGoNoGo({ impact, auditOk: audit.payload.ok, auditDecision: audit.payload.readiness.decision });
+      await Promise.all([
+        writeReportFile4(join(outDir, "go-no-go.md"), decision.markdown),
+        writeReportFile4(join(outDir, "pilot-report.md"), createPilotReport({ impact, status: decision.status, auditOk: audit.payload.ok, auditDecision: audit.payload.readiness.decision }))
+      ]);
+      logger5.title();
+      logger5.line(`Pilot package: ${outDir}`);
+      logger5.line(`Decision: ${decision.status}`);
+      logger5.line(`Impact: ${impact.decision.status}`);
+      logger5.line(`Audit: ${audit.payload.ok ? "passed" : "failed"}`);
+      process.exitCode = decision.status === "go" ? 0 : decision.status === "conditional-go" ? 1 : 1;
+    } catch (error) {
+      logger5.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 2;
+    }
+  });
+}
+async function createPilotImpact(newSchema, options) {
+  const schemaRequest = { headers: parseSchemaRequestHeaders2(options.schemaHeader) };
+  const baseSchema = options.base ? await readGitBaseSchema2(newSchema, { base: options.base, repo: options.repo }) : null;
+  try {
+    const oldSchema = baseSchema?.path ?? options.old;
+    const oldDocument = await parseOpenApi3(oldSchema, schemaRequest);
+    const newDocument = await parseOpenApi3(newSchema, schemaRequest);
+    const report = diffOpenApiContracts2(normalizeOpenApi3(oldDocument), normalizeOpenApi3(newDocument));
+    const sourceUsages = options.repo ? await scanSourceUsages2(options.repo, report) : [];
+    return {
+      ok: report.decision.status !== "blocked",
+      ...baseSchema ? { base: baseSchema.base } : {},
+      oldSchema: baseSchema?.label ?? oldSchema,
+      newSchema,
+      sourceUsages,
+      ...report
+    };
+  } finally {
+    await baseSchema?.cleanup();
+  }
+}
+function createGoNoGo(input) {
+  const blockers = [
+    ...input.impact.decision.status === "blocked" ? ["Impact decision is blocked."] : [],
+    ...!input.auditOk ? ["Audit readiness failed."] : []
+  ];
+  const warnings = [
+    ...input.impact.decision.status === "review" ? ["Impact decision needs review."] : [],
+    ...input.impact.sourceUsages && input.impact.sourceUsages.length === 0 ? ["No impacted source usages were found."] : []
+  ];
+  const status = blockers.length > 0 ? "no-go" : warnings.length > 0 ? "conditional-go" : "go";
+  const lines = [
+    "# Forge Pilot Go/No-Go",
+    "",
+    `Decision: ${status}`,
+    "",
+    "## Evidence",
+    "",
+    ...input.impact.base ? [`- Base ref: ${input.impact.base}`] : [],
+    `- Old schema: ${input.impact.oldSchema}`,
+    `- New schema: ${input.impact.newSchema}`,
+    `- Impact decision: ${input.impact.decision.status}`,
+    `- Impact merge risk: ${input.impact.decision.mergeRisk}`,
+    `- Breaking changes: ${input.impact.summary.breaking}`,
+    `- Warnings: ${input.impact.summary.warnings}`,
+    `- Source usage matches: ${input.impact.sourceUsages?.length ?? 0}`,
+    `- Audit decision: ${input.auditDecision}`,
+    "",
+    "## Blockers",
+    "",
+    ...blockers.length > 0 ? blockers.map((item) => `- ${item}`) : ["No blockers."],
+    "",
+    "## Warnings",
+    "",
+    ...warnings.length > 0 ? warnings.map((item) => `- ${item}`) : ["No warnings."],
+    "",
+    "## Next Actions",
+    "",
+    ...status === "go" ? ["- Add Forge impact and audit checks to CI.", "- Generate the resource layer in a branch and review it with the frontend team."] : status === "conditional-go" ? ["- Review warnings with the frontend owner.", "- Decide whether accepted warnings should be documented in the pilot report."] : ["- Fix blockers before buying or rolling out Forge.", "- Re-run `archora-forge pilot` after schema or config changes."],
+    ""
+  ];
+  return { status, markdown: lines.join("\n") };
+}
+function createPilotReport(input) {
+  return [
+    "# Archora Forge Pilot Report",
+    "",
+    "## Decision",
+    "",
+    `Decision: ${input.status}`,
+    `Impact: ${input.impact.decision.status}`,
+    `Merge risk: ${input.impact.decision.mergeRisk}`,
+    `Audit: ${input.auditOk ? "passed" : "failed"}`,
+    "",
+    "## Artifact Links",
+    "",
+    "- `impact-pr.md` - PR comment for reviewers.",
+    "- `impact.md` - full frontend API impact report.",
+    "- `impact.json` - machine-readable impact payload.",
+    "- `audit/index.html` - generated output audit and readiness report.",
+    "- `audit/report.md` - Markdown audit handoff.",
+    "- `go-no-go.md` - short adoption decision.",
+    "",
+    "## Impact Summary",
+    "",
+    `- Old schema: ${input.impact.oldSchema}`,
+    `- New schema: ${input.impact.newSchema}`,
+    ...input.impact.base ? [`- Base ref: ${input.impact.base}`] : [],
+    `- Breaking changes: ${input.impact.summary.breaking}`,
+    `- Warnings: ${input.impact.summary.warnings}`,
+    `- Non-breaking changes: ${input.impact.summary.nonBreaking}`,
+    `- Source usage matches: ${input.impact.sourceUsages?.length ?? 0}`,
+    "",
+    "## Affected Surface",
+    "",
+    `- Resources: ${formatInlineList(input.impact.affectedResources)}`,
+    `- Generated files: ${formatInlineList(input.impact.affectedFiles)}`,
+    `- Operation IDs: ${formatInlineList(input.impact.impactedSurface.operationIds)}`,
+    `- Client methods: ${formatInlineList(input.impact.impactedSurface.clientMethods)}`,
+    `- Query hooks: ${formatInlineList(input.impact.impactedSurface.queryHooks)}`,
+    "",
+    "## Reviewer Checklist",
+    "",
+    "- Confirm `impact-pr.md` gives a clear merge decision.",
+    "- Confirm `impact.md` names the breaking changes and affected generated files.",
+    "- Confirm `audit/index.html` matches the frontend resource model.",
+    "- Confirm `audit/typecheck.md` passed or every failure is triaged.",
+    "- Confirm `go-no-go.md` matches the team decision before purchase or rollout.",
+    "",
+    "## Next Review Step",
+    "",
+    input.status === "go" ? "Add the generated GitHub workflow, run the first PR with Forge comments enabled, then decide whether to commit generated output." : input.status === "conditional-go" ? "Review warnings with the frontend owner before committing generated output or widening scope." : "Do not roll out Forge on this schema until blockers are fixed or explicitly accepted by the frontend owner.",
+    ""
+  ].join("\n");
+}
+function formatInlineList(values) {
+  return values && values.length > 0 ? values.map((value) => `\`${value}\``).join(", ") : "none";
+}
+
+// src/pro.ts
+function registerProCommands(cli) {
+  registerPilotCommand(cli);
+  registerCiCommand(cli);
+  registerAuditCommand(cli);
+  registerCheckCommand(cli);
+  registerContractDiffCommand(cli);
+}
+export {
+  registerProCommands
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@archora/forge-pro",
+  "version": "2.0.0",
+  "description": "Forge Intelligence: the commercial team/CI layer (impact, check, audit, ci, pilot) for Archora Forge.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/archora-dev/archora-forge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/archora-dev/archora-forge/issues"
+  },
+  "homepage": "https://github.com/archora-dev/archora-forge#readme",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "@archora/forge-cli": "2.0.0",
+    "@archora/forge-core": "2.0.0",
+    "@archora/forge-adapters": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.17",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}