gh-inari 0.5.2 → 0.6.0

package/dist/cli.js

@@ -3,11 +3,12 @@ import { readFile, stat } from "node:fs/promises";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { ArtifactInputError, parseArtifactInputDocument, prepareIssueArtifact, preparePullRequestArtifact, projectExistingArtifact, renderIssueArtifact, renderPullRequestArtifact, selectExistingArtifactCandidate, validateExistingIssueArtifact, validateExistingPullRequestArtifact, } from "./artifact.js";
+import { ArtifactInputError, parseArtifactInputDocument, prepareIssueArtifact, preparePullRequestArtifact, projectExistingArtifact, renderIssueArtifact, renderPullRequestArtifact, } from "./artifact.js";
 import { projectContract, SemanticValidationError, validateSemanticInput, } from "./contract/index.js";
 import { GitHubAdapter, isGitHubAdapterError } from "./github/index.js";
-import { compileLocalGovernedContract, compileRepositoryGovernedContract, compileRepositoryGovernedContracts, createGovernedIssue, createGovernedPullRequest, discoverRepositoryTemplates, rejectGovernedPolicyOverride, } from "./governance.js";
+import { compileLocalGovernedContract, compileRepositoryGovernedContract, createGovernedIssue, createGovernedPullRequest, discoverRepositoryTemplates, rejectGovernedPolicyOverride, } from "./governance.js";
 import { discoverTemplates } from "./template-discovery.js";
+import { applySemanticPatch, assessExistingArtifact, currentArtifactInput, diffArtifact, prepareRemediationArtifact, prepareSyncInput, readGovernedExistingArtifact, RemediationError, updateGovernedExistingArtifact, } from "./reconciliation.js";
 import { discoverSemanticTemplates, importNativeTemplate, renderSemanticCompactSchema, syncSemanticTemplates, SEMANTIC_ISSUE_DIRECTORY, SEMANTIC_PULL_REQUEST_FILE, SEMANTIC_TEMPLATE_DIRECTORY, } from "./semantic-template.js";
 const EXIT_USAGE = 1;
 const EXIT_VALIDATION = 2;
@@ -21,6 +22,19 @@ const RUNTIME_CAPABILITIES = [
     "extension-bootstrap",
 ];
 const CANONICAL_INVOCATION = "gh inari";
+const KNOWN_ARTIFACT_COMMANDS = new Set([
+    "schema",
+    "validate",
+    "render",
+    "create",
+    "explain",
+    "get",
+    "check",
+    "edit",
+    "normalize",
+    "sync",
+]);
+const KNOWN_TEMPLATE_COMMANDS = new Set(["list", "sync", "import"]);
 const INSTALL_COMMAND = "gh extension install yohn-jp/gh-inari";
 const UPDATE_COMMAND = "gh extension upgrade inari";
 const FALLBACK_COMMAND = "npx --yes gh-inari";
@@ -34,6 +48,7 @@ const BOOLEAN_OPTIONS = new Set([
     "maintainerCanModify",
     "compact",
     "check",
+    "dryRun",
 ]);
 const VALUE_OPTIONS = new Set([
     "from",
@@ -50,6 +65,8 @@ const VALUE_OPTIONS = new Set([
 /** The installed gh-inari executable entrypoint. */
 export async function runCli(argv, dependencies = {}) {
     const metadata = dependencies.packageMetadata ?? readPackageMetadata();
+    if (!isOwnedInvocation(argv))
+        return runGhFallback(argv, dependencies);
     let parsed;
     try {
         parsed = parseArguments(argv);
@@ -68,9 +85,10 @@ export async function runCli(argv, dependencies = {}) {
         parsed.positionals[0] === "diagnose" ||
         parsed.positionals[0] === "doctor";
     const versionRequested = parsed.options.version === true || parsed.positionals[0] === "version";
-    if (parsed.options.help === true || (parsed.positionals.length === 0 && !versionRequested && !diagnosticRequested)) {
-        printHelp();
-        return parsed.positionals.length === 0 && parsed.options.help !== true ? EXIT_USAGE : 0;
+    const helpRequested = parsed.options.help !== undefined && parsed.options.help !== false;
+    if (helpRequested || (parsed.positionals.length === 0 && !versionRequested && !diagnosticRequested)) {
+        printHelpFor(parsed.positionals, parsed.options.help);
+        return parsed.positionals.length === 0 && !helpRequested ? EXIT_USAGE : 0;
     }
     const json = parsed.options.json === true;
     try {
@@ -280,6 +298,17 @@ function runGhDiagnosticCommand(args) {
         };
     }
 }
+/** Delegates argv gh-inari does not own to the real `gh` binary, so `gh inari` is a strict superset of `gh`. */
+function runGhFallback(argv, dependencies) {
+    const execute = dependencies.runGhFallback ?? runGhPassthroughCommand;
+    return execute(argv);
+}
+function runGhPassthroughCommand(argv) {
+    const result = spawnSync("gh", [...argv], { stdio: "inherit" });
+    if (result.error)
+        throw new CliError("GH_FALLBACK_FAILED", `Cannot execute gh: ${result.error.message}.`);
+    return result.status ?? EXIT_INTERNAL;
+}
 function hasInariExtension(output) {
     return output.split(/\r?\n/u).some((line) => /^\s*gh\s+inari(?:\s|$)/u.test(line));
 }
@@ -474,6 +503,12 @@ async function runArtifactCommand(domain, command, rest, parsed, root, dependenc
         console.log(JSON.stringify({ ok: true, artifact: created.artifact, governance: created.governance }));
         return 0;
     }
+    if (command === "check" || command === "edit" || command === "normalize" || command === "sync") {
+        if (rest[0] === undefined || !isPositiveInteger(rest[0])) {
+            throw invalidArtifactNumberError(domain, rest[0]);
+        }
+        return runExistingRemediation(domain, command, Number(rest[0]), parsed, root, dependencies, json);
+    }
     if ((command === "validate" || command === "explain") &&
         rest[0] !== undefined &&
         isPositiveInteger(rest[0]) &&
@@ -493,7 +528,9 @@ async function runArtifactCommand(domain, command, rest, parsed, root, dependenc
 }
 async function runExistingValidation(domain, number, parsed, root, dependencies, json) {
     rejectGovernedPolicyOverride(parsed.options.policy);
-    const read = await readExistingArtifact(domain, number, parsed, root, dependencies);
+    const adapter = createAdapter(dependencies, root, parsed.options.repository);
+    await adapter.resolveRepositoryContext();
+    const read = await readGovernedExistingArtifact(adapter, domain, number, templateSelector(parsed, undefined));
     const { remote, result } = read;
     const projection = projectExistingArtifact(result);
     const output = {
@@ -509,7 +546,9 @@ async function runExistingValidation(domain, number, parsed, root, dependencies,
 }
 async function runExistingGet(domain, number, parsed, root, dependencies) {
     rejectGovernedPolicyOverride(parsed.options.policy);
-    const { remote, contract, result } = await readExistingArtifact(domain, number, parsed, root, dependencies);
+    const adapter = createAdapter(dependencies, root, parsed.options.repository);
+    await adapter.resolveRepositoryContext();
+    const { remote, contract, result } = await readGovernedExistingArtifact(adapter, domain, number, templateSelector(parsed, undefined));
     const projection = projectExistingArtifact(result);
     const output = {
         valid: projection.valid,
@@ -527,6 +566,74 @@ async function runExistingGet(domain, number, parsed, root, dependencies) {
     console.log(JSON.stringify(output));
     return result.valid ? 0 : EXIT_VALIDATION;
 }
+async function runExistingRemediation(domain, operation, number, parsed, root, dependencies, json) {
+    void json;
+    rejectGovernedPolicyOverride(parsed.options.policy);
+    const adapter = createAdapter(dependencies, root, parsed.options.repository);
+    await adapter.resolveRepositoryContext();
+    const read = await readGovernedExistingArtifact(adapter, domain, number, templateSelector(parsed, undefined));
+    const assessment = assessExistingArtifact(domain, read);
+    const base = {
+        operation,
+        kind: domain === "issue" ? "issue" : "pull_request",
+        number: read.remote.number,
+        url: read.remote.url,
+        ...(read.contract === undefined ? {} : { template: read.contract.templateIdentity }),
+    };
+    if (operation === "check") {
+        console.log(JSON.stringify({
+            ok: assessment.status === "valid-current",
+            ...base,
+            status: assessment.status,
+            classification: read.result.classification,
+            valid: assessment.status === "valid-current",
+            normalizable: assessment.normalizable,
+            diagnostics: assessment.diagnostics,
+            violations: assessment.status === "non-canonical" ? assessment.diagnostics : read.result.violations,
+        }));
+        return assessment.status === "valid-current" ? 0 : EXIT_VALIDATION;
+    }
+    if (read.contract === undefined) {
+        throw new RemediationError(operation === "normalize" ? "NORMALIZATION_UNSAFE" : "SYNC_CURRENT_UNSUPPORTED", "No authoritative template could be selected for the existing artifact.", "$.template");
+    }
+    let desiredInput;
+    if (operation === "normalize") {
+        if (!read.result.valid || !read.result.parse.parsed) {
+            throw new RemediationError("NORMALIZATION_UNSAFE", "Normalization requires a semantically valid artifact whose values can be round-tripped canonically.", "$.artifact");
+        }
+        desiredInput = currentArtifactInput(domain, read);
+    }
+    else {
+        const input = await readInputDocument(parsed.options.from);
+        desiredInput =
+            operation === "edit" ? applySemanticPatch(domain, read, input) : prepareSyncInput(domain, read, input);
+    }
+    const desired = prepareRemediationArtifact(domain, read.contract, desiredInput);
+    const diff = diffArtifact(domain, read, desired);
+    const resultBase = {
+        ...base,
+        changed: diff.changed,
+        noOp: !diff.changed,
+        diff,
+    };
+    if (!diff.changed || parsed.options.dryRun === true) {
+        console.log(JSON.stringify({
+            ok: true,
+            ...resultBase,
+            ...(parsed.options.dryRun === true ? { dryRun: true, mutation: "not-performed" } : {}),
+        }));
+        return 0;
+    }
+    const mutated = await updateGovernedExistingArtifact(adapter, domain, number, desired);
+    console.log(JSON.stringify({
+        ok: true,
+        ...resultBase,
+        mutation: "applied",
+        artifact: { number: mutated.artifact.number, url: mutated.artifact.url },
+        governance: mutated.governance,
+    }));
+    return 0;
+}
 function existingArtifactMetadata(domain, remote) {
     if (domain === "issue") {
         if (!("labels" in remote) || !("assignees" in remote))
@@ -548,58 +655,6 @@ function existingArtifactMetadata(domain, remote) {
         base: remote.base,
     };
 }
-async function readExistingArtifact(domain, number, parsed, root, dependencies) {
-    const adapter = createAdapter(dependencies, root, parsed.options.repository);
-    await adapter.resolveRepositoryContext();
-    const selector = templateSelector(parsed, undefined);
-    let contracts;
-    let failedTemplates;
-    if (selector === undefined) {
-        const outcomes = await compileRepositoryGovernedContracts(adapter, domain);
-        contracts = outcomes.filter((outcome) => outcome.status === "compiled").map((outcome) => outcome.contract);
-        failedTemplates = outcomes.filter((outcome) => outcome.status === "failed");
-    }
-    else {
-        contracts = [await compileRepositoryGovernedContract(adapter, domain, selector)];
-        failedTemplates = [];
-    }
-    const remote = domain === "issue" ? await adapter.getIssue(number) : await adapter.getPullRequest(number);
-    const candidates = contracts.map((contract) => ({
-        contract,
-        result: domain === "issue"
-            ? validateExistingIssueArtifact(contract, remote.body)
-            : validateExistingPullRequestArtifact(contract, remote.body),
-    }));
-    const selected = selectExistingArtifactCandidate(candidates);
-    if (selected.contract !== undefined || failedTemplates.length === 0) {
-        return { remote, contract: selected.contract, result: selected.result };
-    }
-    // No compiled template matched, and at least one sibling template failed to
-    // compile: fail closed, since the malformed template could be the one that
-    // actually owns this artifact. Surface it as a bounded diagnostic rather
-    // than an opaque compile error.
-    const compileDiagnostics = failedTemplates.map((failed) => ({
-        code: "EXISTING_TEMPLATE_COMPILE_FAILED",
-        path: failed.path,
-        message: `[${failed.path}] Template failed to compile: ${failed.message}`,
-    }));
-    // selected.contract is undefined here, so selectExistingArtifactCandidate resolved this
-    // as an unmatched candidate set: its violations are always ExistingArtifactDiagnostic[].
-    const existingViolations = selected.result.violations;
-    return {
-        remote,
-        result: {
-            valid: false,
-            classification: selected.result.classification,
-            parse: {
-                parsed: false,
-                values: {},
-                diagnostics: [...selected.result.parse.diagnostics, ...compileDiagnostics],
-            },
-            violations: [...existingViolations, ...compileDiagnostics],
-        },
-    };
-}
 function createAdapter(dependencies, root, repository) {
     const factory = dependencies.createAdapter ?? ((options) => new GitHubAdapter(options));
     return factory({ cwd: root, ...(typeof repository === "string" ? { repository } : {}) });
@@ -677,10 +732,14 @@ function parseArguments(argv) {
                 options[key] = true;
                 continue;
             }
-            const booleanValue = token.slice(equalIndex + 1);
-            if (booleanValue !== "true" && booleanValue !== "false")
+            const rawValue = token.slice(equalIndex + 1);
+            if (key === "help" && rawValue === "full") {
+                options[key] = rawValue;
+                continue;
+            }
+            if (rawValue !== "true" && rawValue !== "false")
                 throw new CliError("INVALID_OPTION", `Option --${rawKey} must be true or false.`);
-            options[key] = booleanValue === "true";
+            options[key] = rawValue === "true";
             continue;
         }
         if (!VALUE_OPTIONS.has(key))
@@ -717,7 +776,9 @@ function toErrorShape(error) {
     return { code: "INTERNAL_ERROR", message: error instanceof Error ? error.message : "Operation failed." };
 }
 function classifyExitCode(error) {
-    if (error instanceof SemanticValidationError || error instanceof ArtifactInputError)
+    if (error instanceof SemanticValidationError ||
+        error instanceof ArtifactInputError ||
+        error instanceof RemediationError)
         return EXIT_VALIDATION;
     if (isGitHubAdapterError(error))
         return EXIT_REMOTE;
@@ -744,14 +805,36 @@ function classifyExitCode(error) {
         return EXIT_VALIDATION;
     return EXIT_INTERNAL;
 }
+/**
+ * True when argv targets a command gh-inari implements; false means it must fall back to the real `gh` binary.
+ * `--help` on an unowned domain or subcommand (e.g. `repo view --help`, `pr list --help`) is not claimed here so
+ * that help delegates to real `gh` the same way execution does -- Inari does not reproduce upstream help text.
+ */
+function isOwnedInvocation(argv) {
+    const first = argv.find((token) => !token.startsWith("--"));
+    if (first === undefined)
+        return true;
+    if (first === "diagnose" || first === "doctor" || first === "version" || first === "help")
+        return true;
+    if (argv.includes("--version") || argv.includes("--diagnose") || argv.includes("--doctor"))
+        return true;
+    const helpRequested = argv.some((token) => token === "--help" || token.startsWith("--help="));
+    if (first === "template") {
+        const second = argv.slice(argv.indexOf(first) + 1).find((token) => !token.startsWith("--"));
+        if (helpRequested && second === undefined)
+            return true;
+        return second !== undefined && KNOWN_TEMPLATE_COMMANDS.has(second);
+    }
+    if (first === "issue" || first === "pr") {
+        const second = argv.slice(argv.indexOf(first) + 1).find((token) => !token.startsWith("--"));
+        if (helpRequested && second === undefined)
+            return true;
+        return second !== undefined && KNOWN_ARTIFACT_COMMANDS.has(second);
+    }
+    return false;
+}
 function isMachineCommand(positionals) {
-    return ((positionals.length >= 2 &&
-        (positionals[1] === "schema" ||
-            positionals[1] === "validate" ||
-            positionals[1] === "render" ||
-            positionals[1] === "create" ||
-            positionals[1] === "explain" ||
-            positionals[1] === "get")) ||
+    return ((positionals.length >= 2 && KNOWN_ARTIFACT_COMMANDS.has(positionals[1] ?? "")) ||
         positionals[0] === "diagnose" ||
         positionals[0] === "doctor" ||
         positionals[0] === "version");
@@ -765,12 +848,7 @@ function isMachineCommandTokens(argv) {
     if (domainIndex < 0)
         return false;
     const command = argv[domainIndex + 1];
-    return (command === "schema" ||
-        command === "validate" ||
-        command === "render" ||
-        command === "create" ||
-        command === "explain" ||
-        command === "get");
+    return command !== undefined && KNOWN_ARTIFACT_COMMANDS.has(command);
 }
 function isPositiveInteger(value) {
     return /^[1-9]\d*$/u.test(value);
@@ -805,8 +883,166 @@ async function readStdin() {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-function printHelp() {
-    console.log(`Usage: gh-inari <command> [options]
+const TEMPLATE_LEAVES = {
+    list: {
+        usage: "template list",
+        summary: "List discovered repository-native and semantic templates.",
+        example: "inari template list",
+    },
+    sync: {
+        usage: "template sync [--check]",
+        summary: "Regenerate native GitHub templates from semantic template contracts under .github/inari/.",
+        example: "inari template sync --check",
+    },
+    import: {
+        usage: "template import --from <native-template> [--to <semantic-file>]",
+        summary: "Import a native GitHub template into a semantic template contract. Discovered semantic paths: " +
+            ".github/inari/issues/<id>.json, .github/inari/pull-request.json (single PR template), or " +
+            ".github/inari/pull-requests/<id>.json (multiple PR templates). Other --to paths write successfully " +
+            "but are never discovered.",
+        example: "inari template import --from .github/ISSUE_TEMPLATE/feature.yml",
+    },
+};
+function artifactLeaves(domain) {
+    const noun = domain === "issue" ? "issue" : "pull request";
+    return {
+        schema: {
+            usage: `${domain} schema [template]`,
+            summary: `Print the semantic field schema for a ${noun} template.`,
+            example: `inari ${domain} schema feature --compact`,
+        },
+        validate: {
+            usage: `${domain} validate --template <template> --from <file.json>`,
+            summary: `Validate local JSON input against a template's schema. ` +
+                `To validate an existing ${noun} instead, use \`${domain} validate <number> [--template <template>]\`.`,
+            example: `inari ${domain} validate --template feature --from ${domain}.json`,
+        },
+        render: {
+            usage: `${domain} render --template <template> --from <file.json>`,
+            summary: `Render validated JSON input into canonical Markdown without mutating GitHub.`,
+            example: `inari ${domain} render --template feature --from ${domain}.json`,
+        },
+        create: {
+            usage: `${domain} create --template <template> --from <file.json>`,
+            summary: `Validate, render, and create a governed ${noun} on GitHub.`,
+            example: `inari ${domain} create --template feature --from ${domain}.json`,
+        },
+        explain: {
+            usage: `${domain} explain <number> [--template <template>]`,
+            summary: `Explain why an existing ${noun} does or does not satisfy its governed contract.`,
+            example: `inari ${domain} explain 123`,
+        },
+        get: {
+            usage: `${domain} get <number> [--template <template>] --json`,
+            summary: `Project an existing ${noun} as its canonical semantic JSON.`,
+            example: `inari ${domain} get 123 --json`,
+        },
+        check: {
+            usage: `${domain} check <number> [--template <template>]`,
+            summary: `Check whether an existing ${noun} is normalizable without mutating GitHub.`,
+            example: `inari ${domain} check 123`,
+        },
+        edit: {
+            usage: `${domain} edit <number> --from <file.json> [--dry-run]`,
+            summary: `Apply an explicit semantic patch to an existing ${noun}.`,
+            example: `inari ${domain} edit 123 --from patch.json --dry-run`,
+        },
+        normalize: {
+            usage: `${domain} normalize <number> [--dry-run]`,
+            summary: `Repair an existing ${noun}'s native projection while preserving its existing semantic values.`,
+            example: `inari ${domain} normalize 123 --dry-run`,
+        },
+        sync: {
+            usage: `${domain} sync <number> --from <file.json> [--dry-run]`,
+            summary: `Reconcile an existing ${noun} to a complete desired semantic state.`,
+            example: `inari ${domain} sync 123 --from desired.json --dry-run`,
+        },
+    };
+}
+const GLOBAL_OPTIONS = `  --from <path>       JSON input file, or - for stdin
+  --template <id>     Repository-native template id, path, or unique name
+  --policy <path>     Local PR policy for schema/validate/render --from workflows; forbidden for governed remote operations
+  --repository <r>    GitHub repository override; governed commands use its default-branch governance
+  --title <title>     Issue/PR title for create
+  --head <branch>     PR head branch for create
+  --base <branch>     PR base branch for create
+  --compact            Emit only semantic fields and constraints for schema
+  --check              Check generated native projections without writing
+  --dry-run            Show a bounded remediation diff without mutating GitHub
+  --draft             Create the PR as a draft
+  --maintainer-can-modify
+                      Allow maintainer edits on the PR
+  --json              Emit structured JSON output
+  --version           Print package version
+  --diagnose          Check the canonical gh extension and recovery path
+  --require-capability <id>
+                      Require a capability in --version/--diagnose checks
+  --minimum-version <v>
+                      Require a minimum semantic version in checks
+  --help              Print this help (--help=full for the complete reference)`;
+const DOMAIN_PASSTHROUGH_EXAMPLE = {
+    issue: "issue list",
+    pr: "pr checks",
+    template: "template view",
+};
+/** Dispatches to root, domain, or leaf help by command depth; positionals are pre-parse-error tokens, so any --help value routes here. */
+function printHelpFor(positionals, helpValue) {
+    if (helpValue === "full")
+        return printFullHelp();
+    const [domain, command] = positionals;
+    if (domain === "issue" || domain === "pr") {
+        if (command !== undefined && command in artifactLeaves(domain))
+            return printLeafHelp(artifactLeaves(domain)[command]);
+        return printDomainHelp(domain, artifactLeaves(domain));
+    }
+    if (domain === "template") {
+        if (command !== undefined && command in TEMPLATE_LEAVES)
+            return printLeafHelp(TEMPLATE_LEAVES[command]);
+        return printDomainHelp("template", TEMPLATE_LEAVES);
+    }
+    printRootHelp();
+}
+function printRootHelp() {
+    console.log(`Usage: inari <command> [...]
+
+A governed GitHub CLI. Issue and PR commands under governed templates run
+through Inari; every other command passes through to the real gh binary
+with the original argv and exit status.
+
+Domains:
+  issue      Governed Issue schema, validation, rendering, and lifecycle
+  pr         Governed pull request schema, validation, rendering, and lifecycle
+  template   Semantic template authoring and native template sync
+
+All other commands (e.g. repo, auth, pr list, issue view) are passed through to gh.
+
+Run \`inari <domain> --help\` for that domain's operations.
+Run \`inari --help=full\` for the complete command and option reference.
+Run \`inari --version\` or \`inari --diagnose\` for machine-readable runtime checks.`);
+}
+function printDomainHelp(domain, leaves) {
+    const lines = Object.values(leaves).map((leaf) => `  ${leaf.usage}`);
+    console.log(`Usage: inari ${domain} <command> [...]
+
+Operations:
+${lines.join("\n")}
+
+Commands outside this list under "${domain}" (e.g. \`${DOMAIN_PASSTHROUGH_EXAMPLE[domain]}\`) pass through to gh.
+
+Run \`inari ${domain} <command> --help\` for that command's inputs and an example.`);
+}
+function printLeafHelp(leaf) {
+    console.log(`Usage: inari ${leaf.usage}
+
+${leaf.summary}
+
+Example:
+  ${leaf.example}
+
+Run \`inari --help=full\` for the complete option reference.`);
+}
+function printFullHelp() {
+    console.log(`Usage: inari <command> [options]
 
 Commands:
   template list
@@ -823,6 +1059,10 @@ Commands:
   issue validate <number> [--template <template>]
   issue explain <number> [--template <template>]
   issue get <number> [--template <template>] --json
+  issue check <number> [--template <template>]
+  issue edit <number> --from <file.json> [--dry-run]
+  issue normalize <number> [--dry-run]
+  issue sync <number> --from <file.json> [--dry-run]
   pr schema [template]
   pr validate --template <template> --from <file.json>
   pr render --template <template> --from <file.json>
@@ -830,32 +1070,21 @@ Commands:
   pr validate <number> [--template <template>]
   pr explain <number> [--template <template>]
   pr get <number> [--template <template>] --json
+  pr check <number> [--template <template>]
+  pr edit <number> --from <file.json> [--dry-run]
+  pr normalize <number> [--dry-run]
+  pr sync <number> --from <file.json> [--dry-run]
 
 Options:
-  --from <path>       JSON input file, or - for stdin
-  --template <id>     Repository-native template id, path, or unique name
-  --policy <path>     Local PR policy for schema/validate/render --from workflows; forbidden for governed remote operations
-  --repository <r>    GitHub repository override; governed commands use its default-branch governance
-  --title <title>     Issue/PR title for create
-  --head <branch>     PR head branch for create
-  --base <branch>     PR base branch for create
-  --compact            Emit only semantic fields and constraints for schema
-  --check              Check generated native projections without writing
-  --draft             Create the PR as a draft
-  --maintainer-can-modify
-                      Allow maintainer edits on the PR
-  --json              Emit structured JSON output
-  --version           Print package version
-  --diagnose          Check the canonical gh extension and recovery path
-  --require-capability <id>
-                      Require a capability in --version/--diagnose checks
-  --minimum-version <v>
-                      Require a minimum semantic version in checks
-  --help              Print this help
+${GLOBAL_OPTIONS}
+
+Create always validates and renders before invoking gh. Schema, validate, render, check, and --dry-run remediation never mutate GitHub.
+Edit applies an explicit semantic patch; normalize preserves existing semantic values; sync reconciles a complete desired semantic state.
 
-Create always validates and renders before invoking gh. Schema, validate, and render never mutate GitHub.
+All other commands pass through to the real gh binary unchanged.
 
-Canonical installation: gh extension install yohn-jp/gh-inari
-PATH-independent fallback: npx --yes gh-inari`);
+Canonical install: npm install --global gh-inari
+PATH-independent fallback: npx --yes gh-inari
+Extension compatibility path: gh extension install yohn-jp/gh-inari`);
 }
 //# sourceMappingURL=cli.js.map