gh-inari 0.3.0 → 0.5.3

package/dist/cli.js

@@ -1,19 +1,54 @@
-import { readFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
 import { readFileSync } from "node:fs";
-import { createInterface } from "node:readline";
 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;
 const EXIT_REMOTE = 3;
 const EXIT_INTERNAL = 4;
-const BOOLEAN_OPTIONS = new Set(["help", "json", "version", "draft", "maintainerCanModify"]);
-const VALUE_OPTIONS = new Set(["from", "template", "policy", "repository", "title", "head", "base"]);
+const DIAGNOSTIC_PROTOCOL_VERSION = 1;
+const RUNTIME_CAPABILITIES = [
+    "canonical-invocation",
+    "machine-readable-version",
+    "capability-diagnostics",
+    "extension-bootstrap",
+];
+const CANONICAL_INVOCATION = "gh inari";
+const INSTALL_COMMAND = "gh extension install yohn-jp/gh-inari";
+const UPDATE_COMMAND = "gh extension upgrade inari";
+const FALLBACK_COMMAND = "npx --yes gh-inari";
+const BOOLEAN_OPTIONS = new Set([
+    "help",
+    "json",
+    "version",
+    "diagnose",
+    "doctor",
+    "draft",
+    "maintainerCanModify",
+    "compact",
+    "check",
+    "dryRun",
+]);
+const VALUE_OPTIONS = new Set([
+    "from",
+    "template",
+    "policy",
+    "repository",
+    "title",
+    "head",
+    "base",
+    "to",
+    "requireCapability",
+    "minimumVersion",
+]);
 /** The installed gh-inari executable entrypoint. */
 export async function runCli(argv, dependencies = {}) {
     const metadata = dependencies.packageMetadata ?? readPackageMetadata();
@@ -30,21 +65,32 @@ export async function runCli(argv, dependencies = {}) {
             console.error(`${shape.code}: ${shape.message}`);
         return classifyExitCode(error);
     }
-    if (parsed.options.help === true || (parsed.positionals.length === 0 && parsed.options.version !== true)) {
+    const diagnosticRequested = parsed.options.diagnose === true ||
+        parsed.options.doctor === true ||
+        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;
     }
-    if (parsed.options.version === true) {
-        console.log(`${metadata.name} ${metadata.version}`);
-        return 0;
-    }
-    const root = path.resolve(dependencies.repositoryRoot ?? process.cwd());
     const json = parsed.options.json === true;
     try {
+        if (versionRequested)
+            return runVersion(metadata, parsed.options, json);
+        if (diagnosticRequested)
+            return runDiagnostic(metadata, parsed.options, json, dependencies);
+        const root = path.resolve(dependencies.repositoryRoot ?? process.cwd());
         const [domain, command, ...rest] = parsed.positionals;
         if (domain === "template" && command === "list") {
             return await runTemplateList(root, parsed.options.repository, dependencies);
         }
+        if (domain === "template" && command === "sync") {
+            return await runTemplateSync(root, parsed.options.check === true);
+        }
+        if (domain === "template" && command === "import") {
+            return await runTemplateImport(root, rest, parsed, json);
+        }
         if (domain === "issue" || domain === "pr") {
             return await runArtifactCommand(domain, command, rest, parsed, root, dependencies, json);
         }
@@ -59,6 +105,242 @@ export async function runCli(argv, dependencies = {}) {
         return classifyExitCode(error);
     }
 }
+function runVersion(metadata, options, json) {
+    const info = runtimeInfo(metadata);
+    const requirements = runtimeRequirements(options, false);
+    const missingCapabilities = requirements.capabilities.filter((capability) => !info.capabilities.includes(capability));
+    const versionSupported = requirements.minimumVersion === undefined || versionAtLeast(info.version, requirements.minimumVersion);
+    const ok = missingCapabilities.length === 0 && versionSupported;
+    if (json) {
+        console.log(JSON.stringify({
+            ok,
+            ...info,
+            ...(ok
+                ? {}
+                : {
+                    error: {
+                        code: "RUNTIME_REQUIREMENT_UNMET",
+                        message: runtimeRequirementMessage(info, missingCapabilities, requirements.minimumVersion),
+                        ...(missingCapabilities.length === 0 ? {} : { missingCapabilities }),
+                        ...(requirements.minimumVersion === undefined ? {} : { minimumVersion: requirements.minimumVersion }),
+                        recovery: FALLBACK_COMMAND,
+                    },
+                }),
+        }));
+    }
+    else {
+        console.log(`${metadata.name} ${metadata.version}`);
+        if (!ok)
+            console.error(`gh-inari: ${runtimeRequirementMessage(info, missingCapabilities, requirements.minimumVersion)}`);
+    }
+    return ok ? 0 : EXIT_VALIDATION;
+}
+function runDiagnostic(metadata, options, json, dependencies) {
+    const info = runtimeInfo(metadata);
+    const requirements = runtimeRequirements(options, true);
+    const canonical = probeCanonicalExtension(requirements, dependencies.runDiagnosticCommand);
+    const ok = canonical.status === "ready";
+    const output = {
+        ok,
+        ...info,
+        requiredCapabilities: requirements.capabilities,
+        ...(requirements.minimumVersion === undefined ? {} : { minimumVersion: requirements.minimumVersion }),
+        canonical: {
+            invocation: CANONICAL_INVOCATION,
+            status: canonical.status,
+            ...(canonical.version === undefined ? {} : { version: canonical.version }),
+            ...(canonical.capabilities === undefined ? {} : { capabilities: canonical.capabilities }),
+            ...(canonical.missingCapabilities === undefined ? {} : { missingCapabilities: canonical.missingCapabilities }),
+            ...(canonical.detail === undefined ? {} : { detail: canonical.detail }),
+            recovery: canonical.recovery,
+        },
+    };
+    if (json)
+        console.log(JSON.stringify(output));
+    else {
+        console.log(`${metadata.name} ${metadata.version}`);
+        if (ok)
+            console.log(`${CANONICAL_INVOCATION}: ready (${canonical.version ?? "unknown version"})`);
+        else {
+            console.error(`gh-inari: ${canonicalDiagnosticMessage(canonical)}`);
+            console.error(`Action: ${canonical.recovery}`);
+        }
+    }
+    return ok ? 0 : EXIT_VALIDATION;
+}
+function runtimeInfo(metadata) {
+    return {
+        name: metadata.name,
+        version: metadata.version,
+        protocol: DIAGNOSTIC_PROTOCOL_VERSION,
+        capabilities: [...RUNTIME_CAPABILITIES],
+        invocation: {
+            canonical: CANONICAL_INVOCATION,
+            direct: "gh-inari",
+            fallback: FALLBACK_COMMAND,
+        },
+    };
+}
+function runtimeRequirements(options, defaultCapabilities) {
+    const requestedCapability = options.requireCapability;
+    const capabilities = typeof requestedCapability === "string"
+        ? [requestedCapability]
+        : defaultCapabilities
+            ? [...RUNTIME_CAPABILITIES]
+            : [];
+    const requestedMinimum = options.minimumVersion;
+    if (requestedMinimum !== undefined && typeof requestedMinimum !== "string")
+        throw new CliError("INVALID_OPTION", "Option --minimum-version requires a version value.", "--minimum-version");
+    if (typeof requestedMinimum === "string" && parseVersion(requestedMinimum) === undefined)
+        throw new CliError("INVALID_OPTION", `Option --minimum-version must be a semantic version (received "${requestedMinimum}").`, "--minimum-version");
+    return {
+        capabilities,
+        ...(typeof requestedMinimum === "string" ? { minimumVersion: requestedMinimum } : {}),
+    };
+}
+function probeCanonicalExtension(requirements, runCommand) {
+    const execute = runCommand ?? runGhDiagnosticCommand;
+    const list = execute(["extension", "list"]);
+    if (list.status !== 0) {
+        return {
+            status: "unavailable",
+            detail: diagnosticProcessDetail(list),
+            recovery: FALLBACK_COMMAND,
+        };
+    }
+    if (!hasInariExtension(list.stdout))
+        return { status: "missing", recovery: INSTALL_COMMAND };
+    const version = execute(["inari", "--version", "--json"]);
+    if (version.status !== 0) {
+        return {
+            status: "stale",
+            detail: diagnosticProcessDetail(version),
+            recovery: UPDATE_COMMAND,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(version.stdout.trim());
+    }
+    catch {
+        return {
+            status: "stale",
+            detail: "the installed extension does not support machine-readable version output",
+            recovery: UPDATE_COMMAND,
+        };
+    }
+    if (!isRuntimeInfo(parsed)) {
+        return {
+            status: "stale",
+            detail: "the installed extension returned an incompatible version contract",
+            recovery: UPDATE_COMMAND,
+        };
+    }
+    if (parsed.protocol !== DIAGNOSTIC_PROTOCOL_VERSION) {
+        return {
+            status: "stale",
+            version: parsed.version,
+            capabilities: parsed.capabilities,
+            detail: `the installed extension uses diagnostic protocol ${parsed.protocol}; expected ${DIAGNOSTIC_PROTOCOL_VERSION}`,
+            recovery: UPDATE_COMMAND,
+        };
+    }
+    const missingCapabilities = requirements.capabilities.filter((capability) => !parsed.capabilities.includes(capability));
+    if (missingCapabilities.length > 0 ||
+        (requirements.minimumVersion !== undefined && !versionAtLeast(parsed.version, requirements.minimumVersion))) {
+        return {
+            status: "stale",
+            version: parsed.version,
+            capabilities: parsed.capabilities,
+            ...(missingCapabilities.length === 0 ? {} : { missingCapabilities }),
+            detail: runtimeRequirementMessage(parsed, missingCapabilities, requirements.minimumVersion),
+            recovery: UPDATE_COMMAND,
+        };
+    }
+    return { status: "ready", version: parsed.version, capabilities: parsed.capabilities, recovery: UPDATE_COMMAND };
+}
+function runGhDiagnosticCommand(args) {
+    try {
+        const result = spawnSync("gh", [...args], {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024,
+            timeout: 3_000,
+        });
+        return {
+            status: result.status,
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            ...(result.error === undefined ? {} : { error: result.error.message }),
+        };
+    }
+    catch (error) {
+        return {
+            status: null,
+            stdout: "",
+            stderr: "",
+            error: error instanceof Error ? error.message : "unable to execute gh",
+        };
+    }
+}
+function hasInariExtension(output) {
+    return output.split(/\r?\n/u).some((line) => /^\s*gh\s+inari(?:\s|$)/u.test(line));
+}
+function isRuntimeInfo(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    const invocation = candidate.invocation;
+    return (candidate.ok !== false &&
+        typeof candidate.name === "string" &&
+        candidate.name === "gh-inari" &&
+        typeof candidate.version === "string" &&
+        typeof candidate.protocol === "number" &&
+        Array.isArray(candidate.capabilities) &&
+        candidate.capabilities.every((capability) => typeof capability === "string") &&
+        typeof invocation === "object" &&
+        invocation !== null &&
+        typeof invocation.canonical === "string" &&
+        typeof invocation.direct === "string" &&
+        typeof invocation.fallback === "string");
+}
+function runtimeRequirementMessage(info, missingCapabilities, minimumVersion) {
+    const requirements = [];
+    if (missingCapabilities.length > 0)
+        requirements.push(`missing capability ${missingCapabilities.map((value) => `"${value}"`).join(", ")}`);
+    if (minimumVersion !== undefined && !versionAtLeast(info.version, minimumVersion))
+        requirements.push(`version ${info.version} is older than required ${minimumVersion}`);
+    return requirements.length === 0 ? "runtime requirements are not satisfied" : requirements.join("; ");
+}
+function canonicalDiagnosticMessage(diagnostic) {
+    if (diagnostic.status === "missing")
+        return "the canonical gh extension is not installed";
+    if (diagnostic.status === "unavailable")
+        return diagnostic.detail ?? "the GitHub CLI could not be executed";
+    if (diagnostic.status === "stale")
+        return diagnostic.detail ?? "the installed gh extension is stale";
+    return "the canonical gh extension is ready";
+}
+function diagnosticProcessDetail(result) {
+    const detail = (result.error ?? result.stderr ?? "").trim().split(/\r?\n/u)[0];
+    return detail === "" ? "the GitHub CLI command failed" : detail.slice(0, 240);
+}
+function parseVersion(value) {
+    const match = /^(?:v)?(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value);
+    if (match === null)
+        return undefined;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function versionAtLeast(actual, minimum) {
+    const actualParts = parseVersion(actual);
+    const minimumParts = parseVersion(minimum);
+    if (actualParts === undefined || minimumParts === undefined)
+        return false;
+    for (let index = 0; index < actualParts.length; index += 1) {
+        if (actualParts[index] !== minimumParts[index])
+            return actualParts[index] > minimumParts[index];
+    }
+    return true;
+}
 class CliError extends Error {
     code;
     path;
@@ -71,6 +353,17 @@ class CliError extends Error {
         this.details = details;
     }
 }
+/** Bound for local --from <file> and stdin artifact input, independent of semantic field constraints. */
+const MAX_INPUT_BYTES = 1_048_576;
+function inputTooLargeError(observedBytes) {
+    return new CliError("INPUT_TOO_LARGE", `Input exceeds the maximum allowed size of ${MAX_INPUT_BYTES} bytes.`, "--from", { limitBytes: MAX_INPUT_BYTES, observedBytes });
+}
+function invalidArtifactNumberError(domain, value) {
+    const message = value === undefined
+        ? `A ${domain} number is required.`
+        : `"${value}" is not a valid ${domain} number. Use a positive integer.`;
+    return new CliError("INVALID_ARTIFACT_NUMBER", message, "$argv[0]", { domain, value });
+}
 async function runTemplateList(root, repository, dependencies) {
     let discovery;
     if (typeof repository === "string") {
@@ -81,7 +374,36 @@ async function runTemplateList(root, repository, dependencies) {
     else {
         discovery = await discoverTemplates(root);
     }
-    console.log(JSON.stringify({ templates: discovery.templates }));
+    const semanticTemplates = typeof repository === "string" ? [] : await discoverSemanticTemplates(root);
+    const hint = semanticTemplates.length === 0 && typeof repository !== "string"
+        ? `no semantic templates found under ${SEMANTIC_TEMPLATE_DIRECTORY}/; ` +
+            `expected ${SEMANTIC_ISSUE_DIRECTORY}/<id>.json, ${SEMANTIC_PULL_REQUEST_FILE}, ` +
+            `or ${SEMANTIC_TEMPLATE_DIRECTORY}/pull-requests/<id>.json`
+        : undefined;
+    console.log(JSON.stringify({
+        templates: discovery.templates,
+        semanticTemplates,
+        ...(hint === undefined ? {} : { semanticTemplatesHint: hint }),
+    }));
+    return 0;
+}
+async function runTemplateSync(root, check) {
+    const result = await syncSemanticTemplates(root, check);
+    console.log(JSON.stringify(result));
+    return check && result.changed ? EXIT_VALIDATION : 0;
+}
+async function runTemplateImport(root, rest, parsed, json) {
+    const nativePath = typeof parsed.options.from === "string" ? parsed.options.from : rest[0];
+    if (nativePath === undefined)
+        throw new CliError("INPUT_REQUIRED", "Use template import --from <native-template>.", "--from");
+    const imported = await importNativeTemplate(root, nativePath, typeof parsed.options.to === "string" ? parsed.options.to : undefined);
+    if (json)
+        console.log(JSON.stringify({ ok: true, ...imported }));
+    else {
+        console.log(imported.path);
+        if (imported.warning !== undefined)
+            console.error(`warning: ${imported.warning}`);
+    }
     return 0;
 }
 async function runArtifactCommand(domain, command, rest, parsed, root, dependencies, json) {
@@ -97,7 +419,10 @@ async function runArtifactCommand(domain, command, rest, parsed, root, dependenc
             contract = await compileLocalGovernedContract(domain, root, templateSelector(parsed, rest[0]), parsed.options.policy);
         }
         const projection = projectContract(contract);
-        console.log(JSON.stringify({ contract, template: contract.templateIdentity, ...projection }));
+        if (parsed.options.compact === true)
+            console.log(JSON.stringify({ schema: renderSemanticCompactSchema(contract) }));
+        else
+            console.log(JSON.stringify({ contract, template: contract.templateIdentity, ...projection }));
         return 0;
     }
     if (command === "validate" || command === "render" || command === "create") {
@@ -143,28 +468,42 @@ async function runArtifactCommand(domain, command, rest, parsed, root, dependenc
         if (domain === "issue") {
             const prepared = prepareIssueArtifact(contract, preparedDocument);
             const created = await createGovernedIssue(adapter, prepared.artifact);
-            console.log(JSON.stringify({ ok: true, artifact: created }));
+            console.log(JSON.stringify({ ok: true, artifact: created.artifact, governance: created.governance }));
             return 0;
         }
         const prepared = preparePullRequestArtifact(contract, preparedDocument);
         const created = await createGovernedPullRequest(adapter, prepared.artifact);
-        console.log(JSON.stringify({ ok: true, artifact: created }));
+        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]) &&
         parsed.options.from === undefined) {
         return runExistingValidation(domain, Number(rest[0]), parsed, root, dependencies, true);
     }
-    if (command === "get" && rest[0] !== undefined && isPositiveInteger(rest[0])) {
-        return runExistingGet(domain, Number(rest[0]), parsed, root, dependencies);
+    if (command === "explain" && (rest[0] === undefined || !isPositiveInteger(rest[0]))) {
+        throw invalidArtifactNumberError(domain, rest[0]);
+    }
+    if (command === "get") {
+        if (rest[0] !== undefined && isPositiveInteger(rest[0])) {
+            return runExistingGet(domain, Number(rest[0]), parsed, root, dependencies);
+        }
+        throw invalidArtifactNumberError(domain, rest[0]);
     }
     throw new CliError("UNKNOWN_COMMAND", `Unknown ${domain} command "${command ?? ""}".`);
 }
 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 = {
@@ -180,7 +519,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,
@@ -198,6 +539,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))
@@ -219,23 +628,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);
-    const contracts = selector === undefined
-        ? await compileRepositoryGovernedContracts(adapter, domain)
-        : [await compileRepositoryGovernedContract(adapter, domain, selector)];
-    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);
-    return { remote, contract: selected.contract, result: selected.result };
-}
 function createAdapter(dependencies, root, repository) {
     const factory = dependencies.createAdapter ?? ((options) => new GitHubAdapter(options));
     return factory({ cwd: root, ...(typeof repository === "string" ? { repository } : {}) });
@@ -248,9 +640,16 @@ async function readInputDocument(value) {
         source = await readStdin();
     else {
         try {
+            const stats = await stat(value);
+            if (stats.size > MAX_INPUT_BYTES)
+                throw inputTooLargeError(stats.size);
             source = await readFile(value, "utf8");
+            if (Buffer.byteLength(source, "utf8") > MAX_INPUT_BYTES)
+                throw inputTooLargeError(Buffer.byteLength(source, "utf8"));
         }
         catch (cause) {
+            if (cause instanceof CliError)
+                throw cause;
             const error = new CliError("INPUT_READ_FAILED", `Cannot read input file "${value}".`, "--from");
             if (cause instanceof Error)
                 error.cause = cause;
@@ -346,7 +745,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;
@@ -360,7 +761,10 @@ function classifyExitCode(error) {
             error.code === "INPUT_REQUIRED" ||
             error.code === "INPUT_READ_FAILED"))
         return EXIT_USAGE;
-    if (error instanceof CliError && error.code === "INPUT_INVALID_JSON")
+    if (error instanceof CliError &&
+        (error.code === "INPUT_INVALID_JSON" ||
+            error.code === "INPUT_TOO_LARGE" ||
+            error.code === "INVALID_ARTIFACT_NUMBER"))
         return EXIT_VALIDATION;
     if (isObjectWithCode(error) && error.code === "GOVERNANCE_POLICY_OVERRIDE_FORBIDDEN")
         return EXIT_VALIDATION;
@@ -371,15 +775,26 @@ function classifyExitCode(error) {
     return EXIT_INTERNAL;
 }
 function isMachineCommand(positionals) {
-    return (positionals.length >= 2 &&
+    return ((positionals.length >= 2 &&
         (positionals[1] === "schema" ||
             positionals[1] === "validate" ||
             positionals[1] === "render" ||
             positionals[1] === "create" ||
             positionals[1] === "explain" ||
-            positionals[1] === "get"));
+            positionals[1] === "get" ||
+            positionals[1] === "check" ||
+            positionals[1] === "edit" ||
+            positionals[1] === "normalize" ||
+            positionals[1] === "sync")) ||
+        positionals[0] === "diagnose" ||
+        positionals[0] === "doctor" ||
+        positionals[0] === "version");
 }
 function isMachineCommandTokens(argv) {
+    if (argv.includes("--diagnose") || argv.includes("--doctor") || argv.includes("diagnose") || argv.includes("doctor"))
+        return true;
+    if (argv.includes("--version") || argv.includes("version"))
+        return argv.includes("--json");
     const domainIndex = argv.findIndex((token) => token === "issue" || token === "pr");
     if (domainIndex < 0)
         return false;
@@ -389,7 +804,11 @@ function isMachineCommandTokens(argv) {
         command === "render" ||
         command === "create" ||
         command === "explain" ||
-        command === "get");
+        command === "get" ||
+        command === "check" ||
+        command === "edit" ||
+        command === "normalize" ||
+        command === "sync");
 }
 function isPositiveInteger(value) {
     return /^[1-9]\d*$/u.test(value);
@@ -414,16 +833,27 @@ function requireFile(filePath) {
 }
 async function readStdin() {
     const chunks = [];
-    const reader = createInterface({ input: process.stdin });
-    for await (const line of reader)
-        chunks.push(line);
-    return chunks.join("\n");
+    let totalBytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        totalBytes += buffer.byteLength;
+        if (totalBytes > MAX_INPUT_BYTES)
+            throw inputTooLargeError(totalBytes);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
 }
 function printHelp() {
     console.log(`Usage: gh-inari <command> [options]
 
 Commands:
   template list
+  template sync [--check]
+  template import --from <native-template> [--to <semantic-file>]
+                      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.
   issue schema [template]
   issue validate --template <template> --from <file.json>
   issue render --template <template> --from <file.json>
@@ -431,6 +861,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>
@@ -438,6 +872,10 @@ 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
@@ -447,13 +885,25 @@ Options:
   --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
 
-Create always validates and renders before invoking gh. Schema, validate, and render never mutate GitHub.`);
+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.
+
+Canonical installation: gh extension install yohn-jp/gh-inari
+PATH-independent fallback: npx --yes gh-inari`);
 }
 //# sourceMappingURL=cli.js.map