gh-inari 0.6.1 → 0.8.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "inari",
+  "version": "0.8.0",
+  "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

@@ -119,6 +119,33 @@ npx --yes --package=./gh-inari-<version>.tgz gh-inari --version --json
 
 Inari uses the current `gh` authentication and repository context. It does not maintain a second credential store. Use `--repository owner/name` when the target repository is not the current checkout.
 
+## Codex Plugin
+
+The same published `gh-inari` package is also a valid Codex Plugin — no
+second install artifact is needed. Installing or unpacking `gh-inari` (any
+of the paths above) ships `.codex-plugin/plugin.json` and
+`skills/inari/SKILL.md` alongside the CLI. Codex requires explicit
+marketplace registration and installation via Codex plugin commands to
+activate the skill; standard `npm install` alone does not automatically
+surface the plugin to Codex-aware agents.
+
+To discover and install it from this repository's marketplace:
+
+```bash
+codex plugin marketplace add .
+```
+
+In Codex, run `/plugins`, select the `gh-inari` marketplace, and install
+`inari`. Start a new Codex session after installation so the bundled Skill
+is available.
+
+The Skill is deliberately thin: it identifies governed GitHub Issue/PR/
+template workflows as Inari-owned and routes agents to `inari skill` /
+`inari skill <scenario>` for the actual operational playbooks, and to
+`inari <domain> --help` for exact command syntax. It does not duplicate
+scenario content, so it stays correct as `inari skill` evolves. Raw `gh`
+remains available for anything outside Inari's governed surface.
+
 ## Commands
 
 ```bash
@@ -159,6 +186,11 @@ 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.
 
+`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`.
+
 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`.
 
 `issue get` and `pr get` are canonical-only v1 reads. They resolve the target
@@ -168,7 +200,11 @@ parse the existing artifact with the same parser and semantic validator as
 metadata. Successful reads report `projection: "canonical"`; wrong-template,
 unparseable, ambiguous, and semantically invalid artifacts report structured
 diagnostics with `projection: "unavailable"` and never return guessed fields.
-When `--template` is omitted, all supported candidates are evaluated
+When `--template` is omitted, Inari first looks for the bounded invisible
+template identity marker every rendered artifact now carries. A valid marker
+resolves the contract directly; an unknown, stale, or wrong-kind marker fails
+closed with a diagnostic instead of guessing another template. Artifacts
+without a marker fall back to evaluating all supported candidates
 deterministically; multiple structural matches fail closed. Native template
 boilerplate and raw Markdown are intentionally absent from successful output.
 

package/dist/artifact.d.ts

@@ -1,5 +1,6 @@
-import { type SemanticValidationResult, type SemanticViolation } from "./contract/validation.js";
-import { type CanonicalContract } from "./contract/ir.js";
+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 ValidatedRenderedIssueArtifact, type ValidatedRenderedPullRequestArtifact } from "./github/types.js";
 export interface ArtifactInputMetadata {
     readonly title?: string;
@@ -14,6 +15,40 @@ export interface ArtifactInputDocument {
     readonly fields: Readonly<Record<string, unknown>>;
     readonly metadata: ArtifactInputMetadata;
 }
+/**
+ * A representation-independent candidate entering the canonical contract.
+ * Adapters may decode JSON, native Markdown, an existing GitHub body, or
+ * internal field input, but they never validate or materialize contract
+ * semantics themselves.
+ */
+export type ArtifactCandidateSource = "json" | "markdown" | "existing" | "fields";
+export interface ArtifactCandidate {
+    readonly fields: unknown;
+    readonly metadata: ArtifactInputMetadata;
+    readonly source: ArtifactCandidateSource;
+}
+export interface ArtifactCandidateAdapterResult {
+    readonly parsed: boolean;
+    readonly candidate?: ArtifactCandidate;
+    readonly diagnostics: readonly ExistingArtifactDiagnostic[];
+}
+/** Result of the one candidate -> selected contract -> canonical JSON boundary. */
+export interface CanonicalArtifactLoadResult {
+    readonly valid: boolean;
+    readonly complete: boolean;
+    /** Canonical contract-shaped semantic JSON. Never contains rejected fields. */
+    readonly canonical: Readonly<Record<string, unknown>>;
+    /** Explicit alias for callers that name the output canonical JSON. */
+    readonly canonicalJson: Readonly<Record<string, unknown>>;
+    /** Backward-compatible semantic value name used by renderer callers. */
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly candidate: ArtifactCandidate;
+    readonly acceptedFields: readonly string[];
+    readonly missingFields: PartialSemanticValidationResult["missingFields"];
+    readonly invalidFields: PartialSemanticValidationResult["invalidFields"];
+    readonly diagnostics: ArtifactDiagnosticReport;
+    readonly violations: readonly SemanticViolation[];
+}
 export interface ArtifactMetadataViolation {
     readonly code: "INPUT_METADATA_INVALID";
     readonly path: string;
@@ -23,21 +58,18 @@ export type ArtifactInputErrorCode = "INPUT_DOCUMENT_INVALID" | "INPUT_METADATA_
 export declare class ArtifactInputError extends Error {
     readonly code: ArtifactInputErrorCode;
     readonly path: string;
-    constructor(code: ArtifactInputErrorCode, message: string, path?: string);
+    readonly details?: unknown;
+    constructor(code: ArtifactInputErrorCode, message: string, path?: string, details?: unknown);
 }
 export type ArtifactPreparationErrorCode = "ARTIFACT_PROVENANCE_MISSING" | "ARTIFACT_ROUND_TRIP_INVALID";
-export type ArtifactRoundTripDiagnosticCode = "ROUND_TRIP_PARSE" | "ROUND_TRIP_SEMANTIC" | "ROUND_TRIP_MISMATCH";
-export interface ArtifactRoundTripDiagnostic {
-    readonly code: ArtifactRoundTripDiagnosticCode;
-    readonly path: string;
-    readonly message: string;
-    readonly expected?: unknown;
-    readonly actual?: unknown;
-}
+/** @deprecated Round-trip diagnostics use the shared #118 diagnostic contract. */
+export type ArtifactRoundTripDiagnostic = ArtifactDiagnostic;
+/** @deprecated Use ArtifactDiagnosticCode/ArtifactDiagnosticDetailCode. */
+export type ArtifactRoundTripDiagnosticCode = ArtifactDiagnostic["code"];
 /** Stable failures raised before a mutation-capable artifact is created. */
 export declare class ArtifactPreparationError extends Error {
     readonly code: ArtifactPreparationErrorCode;
-    readonly diagnostics: readonly ArtifactRoundTripDiagnostic[];
+    readonly diagnostics: readonly ArtifactDiagnostic[];
     constructor(code: ArtifactPreparationErrorCode, message: string, diagnostics?: readonly ArtifactRoundTripDiagnostic[]);
 }
 export interface PreparedIssueArtifact {
@@ -51,7 +83,7 @@ export interface PreparedPullRequestArtifact {
     readonly artifact: ValidatedRenderedPullRequestArtifact;
 }
 export type ExistingArtifactClassification = "valid" | "semantic" | "wrong-template" | "unparseable" | "ambiguous";
-export type ExistingArtifactDiagnosticCode = "EXISTING_WRONG_TEMPLATE" | "EXISTING_UNPARSEABLE" | "EXISTING_EXTRA_CONTENT" | "EXISTING_UNKNOWN_CHECKLIST_ITEM" | "EXISTING_AMBIGUOUS_TEMPLATE" | "EXISTING_NON_CANONICAL" | "EXISTING_TEMPLATE_COMPILE_FAILED";
+export type ExistingArtifactDiagnosticCode = "EXISTING_WRONG_TEMPLATE" | "EXISTING_UNPARSEABLE" | "EXISTING_EXTRA_CONTENT" | "EXISTING_UNKNOWN_CHECKLIST_ITEM" | "EXISTING_AMBIGUOUS_TEMPLATE" | "EXISTING_NON_CANONICAL" | "EXISTING_TEMPLATE_COMPILE_FAILED" | "EXISTING_TEMPLATE_MARKER_INVALID";
 export interface ExistingArtifactDiagnostic {
     readonly code: ExistingArtifactDiagnosticCode;
     readonly path: string;
@@ -62,6 +94,15 @@ export interface ExistingArtifactParseResult {
     readonly values: Readonly<Record<string, unknown>>;
     readonly diagnostics: readonly ExistingArtifactDiagnostic[];
 }
+/**
+ * Semantic values recovered from an artifact that did not pass the strict
+ * structural parser. Values are extracted only from unambiguous contract
+ * sections and are still subject to the canonical semantic loader before use.
+ */
+export interface RecoverableArtifactValues {
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly diagnostics: readonly ExistingArtifactDiagnostic[];
+}
 export interface ExistingArtifactValidationResult {
     readonly valid: boolean;
     readonly classification: ExistingArtifactClassification;
@@ -82,6 +123,38 @@ export interface ExistingPullRequestReader {
         readonly url: string;
     }>;
 }
+/**
+ * Bounded invisible template identity marker embedded in newly rendered
+ * artifacts. It is the primary template-selection signal for governed
+ * read/repair/validation; legacy artifacts without a marker (or with one
+ * that cannot be trusted) fall back to deterministic structural matching.
+ * The marker is metadata only: it never substitutes for the authoritative
+ * repository governance/provenance that resolves the actual contract.
+ */
+export declare const TEMPLATE_IDENTITY_MARKER_VERSION: "1";
+export interface TemplateIdentityMarker {
+    readonly version: string;
+    readonly kind: ArtifactKind;
+    readonly path: string;
+}
+export type TemplateIdentityMarkerStatus = "absent" | "valid" | "malformed" | "unsupported-version";
+export interface TemplateIdentityMarkerExtraction {
+    readonly status: TemplateIdentityMarkerStatus;
+    readonly marker?: TemplateIdentityMarker;
+    /** Body with a recognized trailing marker line removed; unchanged when none is present. */
+    readonly body: string;
+}
+/**
+ * Recognize and remove a trailing template identity marker line without
+ * applying semantic parsing. Only a line starting with the exact reserved
+ * marker prefix is treated as a marker attempt at all; ordinary trailing
+ * HTML comments (e.g. PR template scaffolding) are left untouched here and
+ * handled by the existing comment-stripping path. Once the reserved prefix
+ * is detected, the line is never silently ignored as "absent" again: an
+ * oversized, truncated, or otherwise broken marker attempt fails closed as
+ * "malformed" instead of falling through to structural matching.
+ */
+export declare function extractTemplateIdentityMarker(body: string): TemplateIdentityMarkerExtraction;
 export interface FetchedExistingArtifact {
     readonly number: number;
     readonly url: string;
@@ -89,6 +162,41 @@ export interface FetchedExistingArtifact {
 }
 /** Parse the documented JSON input envelope while keeping field semantics adapter-independent. */
 export declare function parseArtifactInputDocument(input: unknown): ArtifactInputDocument;
+/** Adapt a parsed JSON envelope without granting it canonical status. */
+export declare function adaptJsonArtifactCandidate(input: unknown): ArtifactCandidate;
+/** Adapt internal structured fields to the same candidate shape as JSON. */
+export declare function adaptFieldArtifactCandidate(fields: unknown, metadata?: ArtifactInputMetadata): ArtifactCandidate;
+/** Alias used by command adapters that call this input the CLI field path. */
+export declare const adaptCliFieldCandidate: typeof adaptFieldArtifactCandidate;
+/** Generic adapter spelling for callers that already hold structured fields. */
+export declare const adaptArtifactCandidate: typeof adaptFieldArtifactCandidate;
+/** Adapt an existing native artifact body through the repository parser. */
+export declare function adaptMarkdownArtifactCandidate(contractInput: unknown, body: string | null | undefined): ArtifactCandidateAdapterResult;
+/** Existing GitHub bodies use the same native Markdown adapter by design. */
+export declare function adaptExistingArtifactCandidate(contractInput: unknown, body: string | null | undefined): ArtifactCandidateAdapterResult;
+/**
+ * Reload a candidate against the selected canonical contract.  Complete input
+ * takes the normal one-pass validator (and therefore may materialize contract
+ * defaults); incomplete/invalid input uses the bounded partial contract and
+ * exposes only accepted semantic values.
+ */
+export declare function loadCanonicalArtifact(contractInput: unknown, candidateInput: unknown): CanonicalArtifactLoadResult;
+/** Explicitly named alias for callers that pass a candidate object. */
+export declare const loadCanonicalCandidate: typeof loadCanonicalArtifact;
+/** Load a JSON representation through the canonical contract boundary. */
+export declare function loadCanonicalJsonArtifact(contractInput: unknown, input: unknown): CanonicalArtifactLoadResult;
+/** Load native Markdown through the same parser and canonical contract. */
+export declare function loadCanonicalMarkdownArtifact(contractInput: unknown, body: string | null | undefined): CanonicalArtifactLoadResult;
+/** Existing-body spelling retained so read/repair callers share one boundary. */
+export declare function loadCanonicalExistingArtifact(contractInput: unknown, body: string | null | undefined): CanonicalArtifactLoadResult;
+/** Classify an artifact input envelope without applying semantic defaults. */
+export declare function validatePartialArtifactInput(contractInput: unknown, input: unknown): PartialSemanticValidationResult;
+/** Terminology alias for callers that treat validation as classification. */
+export declare const classifyPartialArtifactInput: typeof validatePartialArtifactInput;
+/** Merge only a targeted field patch into a prior stateless partial result. */
+export declare function repairPartialArtifactInput(contractInput: unknown, previous: unknown, patch?: unknown): PartialSemanticRepairResult;
+/** Terminology alias for callers that describe targeted repair as a merge. */
+export declare const mergePartialArtifactInput: typeof repairPartialArtifactInput;
 export declare function renderIssueArtifact(contractInput: unknown, input: unknown): string;
 export declare function renderPullRequestArtifact(contractInput: unknown, input: unknown): string;
 /** Construct the only values accepted by the GitHub mutation adapter. */
@@ -96,6 +204,14 @@ export declare function prepareIssueArtifact(contractInput: unknown, input: Arti
 export declare function preparePullRequestArtifact(contractInput: unknown, input: ArtifactInputDocument): PreparedPullRequestArtifact;
 export declare function parseExistingIssueArtifact(contractInput: unknown, body: string | null | undefined): ExistingArtifactParseResult;
 export declare function parseExistingPullRequestArtifact(contractInput: unknown, body: string | null | undefined): ExistingArtifactParseResult;
+/**
+ * Recover field values from a malformed or wrong-template body without
+ * weakening the strict existing-artifact parser. The section boundaries and
+ * field decoding are the same parser primitives used by strict parsing; only
+ * the order/complete-structure requirement is relaxed for an explicitly
+ * 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 validateExistingPullRequestArtifact(contractInput: unknown, body: string | null | undefined): ExistingArtifactValidationResult;
 export interface ExistingArtifactCandidate {