gh-inari 0.8.0 → 0.10.2

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "inari",
-  "version": "0.8.0",
+  "version": "0.10.2",
   "description": "Governed GitHub Issue/PR/template workflows via the inari CLI. Prefer inari over raw gh for operations it owns; use inari skill for operational playbooks.",
   "skills": "skills/inari"
 }

package/README.md

@@ -90,8 +90,10 @@ recovery command. The current capability identifiers are
 `canonical-invocation`, `machine-readable-version`, `capability-diagnostics`,
 and `extension-bootstrap`.
 
-The `inari`, `gh-inari`, and `gh inari` invocation forms are behaviorally
-identical:
+The `inari` executable is canonical. The direct package executable
+`gh-inari` and the `gh inari` extension form are compatibility paths with the
+same governed command semantics; prefer `inari` for agent and human-facing
+commands:
 
 ```bash
 inari issue schema feature --json
@@ -166,8 +168,8 @@ inari issue get <number> [--template <template>] --json
 inari pr get <number> [--template <template>] --json
 inari issue check <number> [--template <template>]
 inari pr check <number> [--template <template>]
-inari issue edit <number> --from patch.json [--dry-run]
-inari pr edit <number> --from patch.json [--dry-run]
+inari issue edit <number> [--from patch.json] [--field name=value] [--title title] [--dry-run]
+inari pr edit <number> [--from patch.json] [--field name=value] [--title title] [--base branch] [--maintainer-can-modify] [--dry-run]
 inari issue normalize <number> [--dry-run]
 inari pr normalize <number> [--dry-run]
 inari issue sync <number> --from desired.json [--dry-run]
@@ -184,12 +186,14 @@ inari pr sync <number> --from desired.json [--dry-run]
 }
 ```
 
-The `fields` object is the semantic input contract shown by `schema`. Issue creation also accepts `assignees`; pull request creation accepts `head`, `base`, `draft`, and `maintainerCanModify`. `--title`, `--head`, and `--base` override envelope metadata.
+The `fields` object is the semantic input contract shown by `schema`; the same schema output exposes the separate required create metadata schema. Issue creation also accepts `assignees`; pull request creation accepts `head`, `base`, `draft`, and `maintainerCanModify`. Caller-supplied `title` metadata is required for both create commands, and `--title`, `--head`, and `--base` override envelope metadata. Existing `edit` commands use the remote artifact as their patch base: `--title` is supported for Issues and pull requests, while pull requests also support `--base` and `--maintainer-can-modify`; `--draft` is rejected for edit because pull-request PATCH does not accept it. Omitted values are preserved and unsupported or immutable metadata is rejected.
 
 `pr sync --from` accepts a complete pull-request desired-state envelope. Use
 `inari pr sync --help` for the top-level contract, or
 `inari pr schema <template> --json` for its machine-readable `syncInput.schema`
 and a valid `syncInput.minimalExample`.
+`issue sync --from` overlays supplied semantic fields and metadata onto the
+current artifact, preserving values omitted from the input.
 
 Schema and validation output is JSON. `--json` makes render and create output JSON as well. Validation failures return exit status `2`; usage errors return `1`; GitHub/transport failures return `3`. Error objects contain stable `code`, `path` where applicable, and ordered `violations`.
 
@@ -211,18 +215,22 @@ boilerplate and raw Markdown are intentionally absent from successful output.
 Existing artifact remediation uses one semantic pipeline for both Issues and
 pull requests. `check` is read-only and classifies an artifact as
 `valid-current`, `non-canonical`, `semantically-invalid`, `unsupported`, or
-`ambiguous`. `edit` applies only an explicit semantic patch from JSON; it never
-accepts raw Markdown as the mutation contract. `normalize` re-renders a
+`ambiguous`. `edit` applies an explicit semantic/metadata patch from JSON or
+direct CLI options; it never accepts raw Markdown as the mutation contract. `normalize` re-renders a
 parseable, semantically valid artifact and fails closed when preservation is
-not proven. `sync` treats its input as the complete desired semantic state and
-reconciles the canonical projection deterministically. A successful no-op is
+not proven. `issue sync` overlays its input onto the current canonical state,
+while `pr sync` treats its input as the complete desired semantic state; both
+reconcile the canonical projection deterministically. A successful no-op is
 reported explicitly, and `--dry-run` returns a bounded semantic/rendered diff
-without calling a GitHub mutation.
+plus the validated resulting fields, metadata, and canonical body without
+calling a GitHub mutation.
 
 ## Source of truth and supported semantics
 
 `.github/ISSUE_TEMPLATE/**` remains the Issue source of truth. For pull requests, Inari discovers GitHub's supported repository locations: `pull_request_template` files under the repository root, `docs/`, or `.github/`, plus `PULL_REQUEST_TEMPLATE/` directories under each location. Native PR template filenames and the `.md`/`.txt` extensions supported by Inari are matched case-insensitively. Other PR-template extension surfaces are intentionally unsupported in v1 and fail closed. Inari discovers and compiles those files; it does not replace them with a proprietary body schema. Supported Issue Form nodes are `input`, `textarea` (including native `render` code fences), single- and multi-select `dropdown`, `checkboxes`, and `markdown`. Browser-only or ambiguous behavior, such as uploads or unsupported textarea rendering modes, fails closed. Markdown nodes are retained for contract/schema explainability but never emitted into an Issue body.
 
+Issue dependencies are a separate, template-independent semantic object. Structured Issue envelopes may provide `dependencies.blockedBy` and `dependencies.blocks`; each reference is the canonical `{ "repositoryHost": "github.com", "repositoryId": "<decimal REST repository database id>", "repository": "owner/name", "number": N }` identity. `repositoryHost` plus `repositoryId` is authoritative: the host/install boundary prevents IDs from different GH_HOST/GHES installations colliding. Within one host, rename/transfer preserves the repository identity tuple and changes only the optional locator; cross-host migration is a different identity. The GitHub adapter obtains this decimal ID from the REST repository endpoint through `gh api`, including for repository overrides through a read-only identity lookup; a context that cannot obtain it does not synthesize one from owner/name. Inari sorts and validates these references (including duplicate, self, malformed, and contradictory declarations) before rendering. Non-empty dependencies are preserved in a bounded reserved body marker and projected back as normalized JSON; ordinary Markdown and GitHub-native dependency metadata are never inferred as semantic input. GitHub-native dependency state is not currently mutated by Inari, so there is no competing authority or implicit drift reconciliation.
+
 Native PR Markdown expresses structure but not policy. A small versioned overlay may add constraints unavailable in Markdown without changing section order or content. The supported v1 form is:
 
 ```yaml
@@ -254,7 +262,23 @@ templates:
 
 Template and section bindings are deterministic. Stale, unknown, or ambiguous template/section references fail closed. `linkedIssue: true` means that the field contains a GitHub closing reference: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, or `resolved`, followed by `#ISSUE-NUMBER` or `OWNER/REPOSITORY#ISSUE-NUMBER`, with an optional colon and case-insensitive keyword. This validates syntax only; GitHub applies automatic linking/closure only under its own contextual rules, including the target default branch.
 
-Issue Form top-level `title` is the exact default title used when the caller omits a title; an explicit caller title replaces it without inferred prefix concatenation. Top-level `labels` are repository-governed defaults and are always retained; caller-supplied labels are appended in order with duplicates removed. Top-level `assignees`, `projects`, and `type`, and upload fields remain unsupported and fail closed rather than being approximated.
+When `issue create` or `pr create` omits `--template`, the shared resolver uses
+the repository's optional `.github/inari/template-resolution.yml` authority:
+
+```yaml
+version: 1
+defaults:
+  issue: feature
+  pr: default
+```
+
+The precedence is explicit selector, configured default, sole candidate,
+interactive TTY selection, then bounded failure. Non-interactive execution never
+guesses among multiple candidates. An invalid or unavailable configured default
+also fails closed. Candidate identifiers and an explicit `--template` recovery
+action are included in structured ambiguity diagnostics.
+
+Issue Form top-level `title` is a fixed native prefix for create validation, but it does not satisfy the caller's required title metadata by itself. An explicit caller title is used as supplied without inferred prefix concatenation or automatic generation. Top-level `labels` are repository-governed defaults and are always retained; caller-supplied labels are appended in order with duplicates removed. Top-level `assignees`, `projects`, and `type`, and upload fields remain unsupported and fail closed rather than being approximated.
 
 ## Scope
 

package/dist/artifact.d.ts

@@ -1,6 +1,7 @@
 import { type PartialSemanticValidationResult, type PartialSemanticRepairResult, type SemanticValidationResult, type SemanticViolation } from "./contract/validation.js";
 import { type ArtifactDiagnostic, type ArtifactDiagnosticReport } from "./diagnostics.js";
 import { type ArtifactKind, type CanonicalContract } from "./contract/ir.js";
+import { type IssueDependencies, type IssueReference } from "./contract/issue-reference.js";
 import { type ValidatedRenderedIssueArtifact, type ValidatedRenderedPullRequestArtifact } from "./github/types.js";
 export interface ArtifactInputMetadata {
     readonly title?: string;
@@ -14,6 +15,8 @@ export interface ArtifactInputMetadata {
 export interface ArtifactInputDocument {
     readonly fields: Readonly<Record<string, unknown>>;
     readonly metadata: ArtifactInputMetadata;
+    /** Generic Issue relationships, independent of template-specific fields. */
+    readonly dependencies?: IssueDependencies;
 }
 /**
  * A representation-independent candidate entering the canonical contract.
@@ -26,6 +29,7 @@ export interface ArtifactCandidate {
     readonly fields: unknown;
     readonly metadata: ArtifactInputMetadata;
     readonly source: ArtifactCandidateSource;
+    readonly dependencies?: IssueDependencies;
 }
 export interface ArtifactCandidateAdapterResult {
     readonly parsed: boolean;
@@ -48,13 +52,14 @@ export interface CanonicalArtifactLoadResult {
     readonly invalidFields: PartialSemanticValidationResult["invalidFields"];
     readonly diagnostics: ArtifactDiagnosticReport;
     readonly violations: readonly SemanticViolation[];
+    readonly dependencies?: IssueDependencies;
 }
 export interface ArtifactMetadataViolation {
     readonly code: "INPUT_METADATA_INVALID";
     readonly path: string;
     readonly message: string;
 }
-export type ArtifactInputErrorCode = "INPUT_DOCUMENT_INVALID" | "INPUT_METADATA_INVALID";
+export type ArtifactInputErrorCode = "INPUT_DOCUMENT_INVALID" | "INPUT_METADATA_INVALID" | "INPUT_DEPENDENCIES_INVALID";
 export declare class ArtifactInputError extends Error {
     readonly code: ArtifactInputErrorCode;
     readonly path: string;
@@ -92,6 +97,9 @@ export interface ExistingArtifactDiagnostic {
 export interface ExistingArtifactParseResult {
     readonly parsed: boolean;
     readonly values: Readonly<Record<string, unknown>>;
+    readonly dependencies?: IssueDependencies;
+    /** Raw dependency declaration retained for the semantic validation boundary. */
+    readonly dependencyInput?: unknown;
     readonly diagnostics: readonly ExistingArtifactDiagnostic[];
 }
 /**
@@ -101,6 +109,7 @@ export interface ExistingArtifactParseResult {
  */
 export interface RecoverableArtifactValues {
     readonly values: Readonly<Record<string, unknown>>;
+    readonly dependencies?: IssueDependencies;
     readonly diagnostics: readonly ExistingArtifactDiagnostic[];
 }
 export interface ExistingArtifactValidationResult {
@@ -115,6 +124,8 @@ export interface ExistingIssueReader {
     getIssue(issueNumber: number): Promise<{
         readonly body: string | null;
         readonly url: string;
+        readonly repositoryId?: string;
+        readonly repositoryHost?: string;
     }>;
 }
 export interface ExistingPullRequestReader {
@@ -132,6 +143,7 @@ export interface ExistingPullRequestReader {
  * repository governance/provenance that resolves the actual contract.
  */
 export declare const TEMPLATE_IDENTITY_MARKER_VERSION: "1";
+export declare const ISSUE_DEPENDENCY_MARKER_VERSION: "1";
 export interface TemplateIdentityMarker {
     readonly version: string;
     readonly kind: ArtifactKind;
@@ -144,6 +156,18 @@ export interface TemplateIdentityMarkerExtraction {
     /** Body with a recognized trailing marker line removed; unchanged when none is present. */
     readonly body: string;
 }
+export type IssueDependencyMarkerStatus = "absent" | "valid" | "malformed" | "unsupported-version";
+export interface IssueDependencyMarkerExtraction {
+    readonly status: IssueDependencyMarkerStatus;
+    readonly dependencies?: IssueDependencies;
+    /** Body with a recognized trailing dependency marker removed. */
+    readonly body: string;
+}
+/**
+ * Read only the reserved trailing dependency marker emitted by Inari.  No
+ * ordinary Markdown is interpreted as a relationship declaration.
+ */
+export declare function extractIssueDependencyMarker(body: string): IssueDependencyMarkerExtraction;
 /**
  * Recognize and remove a trailing template identity marker line without
  * applying semantic parsing. Only a line starting with the exact reserved
@@ -212,7 +236,7 @@ export declare function parseExistingPullRequestArtifact(contractInput: unknown,
  * selected repair target.
  */
 export declare function recoverExistingArtifactValues(contractInput: unknown, body: string | null | undefined): RecoverableArtifactValues;
-export declare function validateExistingIssueArtifact(contractInput: unknown, body: string | null | undefined): ExistingArtifactValidationResult;
+export declare function validateExistingIssueArtifact(contractInput: unknown, body: string | null | undefined, subject?: IssueReference): ExistingArtifactValidationResult;
 export declare function validateExistingPullRequestArtifact(contractInput: unknown, body: string | null | undefined): ExistingArtifactValidationResult;
 export interface ExistingArtifactCandidate {
     readonly contract: CanonicalContract;
@@ -227,6 +251,7 @@ export interface ExistingArtifactProjection {
     readonly projection: "canonical" | "unavailable";
     readonly classification: ExistingArtifactClassification;
     readonly fields?: Readonly<Record<string, unknown>>;
+    readonly dependencies?: IssueDependencies;
     readonly diagnostics: readonly ExistingArtifactDiagnostic[];
     readonly violations?: readonly SemanticViolation[];
     readonly attemptedTemplates?: readonly string[];
@@ -239,6 +264,8 @@ export declare function selectExistingArtifactCandidate(candidates: readonly Exi
 export declare function validateRequiredMetadataString(value: unknown, key: string): ArtifactMetadataViolation | undefined;
 export declare function validateExistingIssueFromAdapter(reader: ExistingIssueReader, contract: unknown, issueNumber: number): Promise<FetchedExistingArtifact>;
 export declare function validateExistingPullRequestFromAdapter(reader: ExistingPullRequestReader, contract: unknown, pullRequestNumber: number): Promise<FetchedExistingArtifact>;
+/** @internal Validate the canonical Issue metadata handoff before mutation. */
+export declare function verifyIssueMetadataRoundTrip(expected: Readonly<Record<string, unknown>>, artifact: ValidatedRenderedIssueArtifact): void;
 /** Escape only Markdown constructs that could change the canonical section structure. */
 export declare function escapeMarkdownValue(value: string): string;
 export declare function removeHtmlComments(value: string): string;