feat: zipnative-cli 1.0.0 — the agent-grade ZIP CLI on zipnative 1.0.0

.github/AGENT_RULES.md

@@ -0,0 +1,103 @@
+# AI Agent Rules for the zipnative ecosystem
+
+> Machine-readable companion: [.github/ai-governance.json](ai-governance.json).
+> This file is the human-and-agent-readable protocol every coding agent
+> (Copilot, Cursor, Claude, Antigravity, Aider, Cline, Windsurf, Gemini CLI, …)
+> **must** follow before proposing an issue, pull request, or dependency change
+> in the zipnative ecosystem (`zipnative`, `zipnative-cli`, `zipnative-mcp`).
+> The rules below are the same text the CLI prints (`AGENT_RULES_TEXT` in
+> `src/utils/governance.ts`) — keep the two in sync.
+
+You are an AI assistant helping a user develop or fix zipnative (or its CLI
+or MCP packages). You act as a **DRAFTSMAN**, never as an autonomous submitter.
+
+The CLI ships this contract as a first-class capability — validate any draft
+locally with:
+
+```bash
+zipnative govern verify-issue ./draft.md      # exit 1 / E_POLICY on a violation
+zipnative govern rules                        # print this protocol
+zipnative govern policy                       # print the machine-readable policy
+```
+
+## Mandatory pre-issue rules
+
+1. Zero runtime dependencies. Never suggest, add, or import an external npm
+   package for a runtime feature. This is a non-negotiable blocker.
+2. No duplicates. Search open AND closed issues/PRs before proposing anything.
+3. Local validation & reproduction. Create and EXECUTE a minimal reproduction
+   locally (an archive, or a script that crafts one). If it does not fail, do
+   not propose an issue.
+4. Byte-identity awareness. Bytes written under `deterministic: true` are a
+   frozen semver contract; any intentional byte change is a MAJOR bump.
+5. Never weaken a security default. rejectTraversal, rejectSymlinks,
+   onDuplicate, every ZipLimits bound, and the CLI's extraction-sink
+   containment stay as they are unless a human records the decision.
+6. No anti-goals. Do not propose encryption, other archive formats,
+   multi-disk archives, archive repair, or filesystem/network I/O inside the
+   engine — these are documented non-goals.
+7. Human-in-the-loop gate (ethics). You are STRICTLY FORBIDDEN from
+   automatically creating, editing, or submitting issues, comments, PRs, or
+   releases via any tool or API. Produce a local markdown draft and present it
+   to the user with a compliance report. The user must explicitly approve and
+   trigger any submission.
+8. Identity integrity. Remind the user that anything submitted is published
+   under THEIR GitHub identity and that they share responsibility for it.
+
+## Human-in-the-loop workflow
+
+```
+[Agent detects bug/improvement]
+            │
+            ▼
+ [Local validation & reproduction]
+            │
+            ▼
+[Verify zero-dependency + no anti-goal + no weakened default]
+            │
+            ▼
+ [Generate draft markdown in .github/drafts/]   (git-ignored except README/TEMPLATE)
+            │
+            ▼
+[Present draft + compliance report to user]
+            │
+            ▼
+ [User explicitly reviews & signs off]   ◄─── CRITICAL ETHICAL GATE
+            │
+            ▼
+ [User manually submits or approves the API call]
+```
+
+## Compliance report (present with every draft)
+
+Include, at minimum:
+
+- **Zero-dependency confirmed** — no new runtime dependency introduced.
+- **Reproduction command** — the exact command you ran (an archive, or the
+  script that crafted one).
+- **Reproduction result** — the observed failure/regression, incl. the `--json`
+  envelope (`E_*` code and `ZIP_*` zipCode).
+- **Duplicate search** — what you searched and what you found.
+- **Affected packages** — which ecosystem packages are impacted (engine root
+  causes are filed upstream in `zipnative`, not here).
+- **Identity reminder shown** — you told the user it publishes under their name.
+
+## Validate a draft before presenting it
+
+```bash
+zipnative govern verify-issue .github/drafts/my-issue.md
+```
+
+The verifier fails when the draft proposes an external dependency or omits a
+reproduction code block, and warns when it reads like an anti-goal proposal or
+lacks a recommended field. A passing check is **NECESSARY BUT NOT SUFFICIENT** —
+the human review gate above always applies.
+
+## What agents must NOT do
+
+- Add a runtime dependency.
+- Weaken a security default or change deterministic bytes silently.
+- Open, edit, label, close, or comment on issues/PRs autonomously.
+- Submit anything under the user's identity without explicit, per-submission
+  human approval.
+- Bypass local validation or duplicate checks.

.github/CODEOWNERS

@@ -0,0 +1,27 @@
+# CODEOWNERS — GitHub auto-assigns reviewers for pull requests
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owner for everything
+* @Nizoka
+
+# CLI commands
+src/commands/ @Nizoka
+
+# Utilities and core bridge
+src/utils/ @Nizoka
+src/core-bridge/ @Nizoka
+
+# Public entry point
+src/index.ts @Nizoka
+
+# Corpus generator + vendored veraZIP validator (raw bytes live here)
+scripts/ @Nizoka
+
+# Documentation and samples (counts are pinned by tests/docs/)
+docs/ @Nizoka
+samples/ @Nizoka
+
+# CI/CD and release
+.github/workflows/ @Nizoka
+package.json @Nizoka
+tsup.config.ts @Nizoka

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: Nizoka
+custom: ['https://plika.app']

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,71 @@
+---
+name: Bug Report
+about: Report a bug in zipnative-cli
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+<!-- A clear description of the bug. -->
+
+## CLI Command & Flags
+
+```
+zipnative <command> [...flags]
+```
+
+<!-- Paste the exact command you ran. -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen? -->
+
+## Actual Behavior
+
+<!-- What happens instead? Include the full error output. Re-run with
+     `--json` and paste the whole envelope from stderr — the `error.code`
+     (E_*) and `error.zipCode` (ZIP_*) are what we branch on:
+
+     zipnative <command> [...flags] --json 2>&1 1>/dev/null
+-->
+
+```json
+{ "ok": false, "command": "...", "error": { "code": "E_...", "zipCode": "ZIP_...", "message": "..." } }
+```
+
+## Environment
+
+- **zipnative-cli version:** <!-- zipnative --version -->
+- **zipnative version:** <!-- zipnative doctor --format json  (reports both, plus the active deflate tier) -->
+- **Runtime:** <!-- Node.js 22 / 24 (node --version) -->
+- **OS:** <!-- incl. filesystem when relevant: NTFS / APFS (case-insensitive) / ext4 -->
+
+## Minimal Reproduction
+
+```bash
+# Smallest shell command / manifest that demonstrates the issue
+```
+
+<!-- For an archive the CLI mishandles: attach the archive (as a .zip inside
+     a .zip so GitHub keeps the bytes intact), or a generator script that
+     crafts it, or at least the output of:
+
+     zipnative inspect --input <a.zip> --format json --entries
+-->
+
+```json
+// If using a JSON manifest (--from-manifest / --manifest), paste the minimal content here
+```
+
+## Additional Context
+
+<!-- Diagnostics (`warning: [ZIP_*]` lines on stderr), `zipnative verify --format json`
+     output, what another tool (unzip, 7z, Explorer) says about the same archive -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/Nizoka/zipnative-cli/security/advisories/new
+    about: Never in a public issue. GitHub private vulnerability reporting is the channel today; SECURITY.md describes the disclosure procedure and the engine-vs-CLI split.
+  - name: Questions and discussions (zipnative ecosystem)
+    url: https://github.com/Nizoka/zipnative/discussions
+    about: How-to questions, design ideas and anything open-ended about the engine or its CLI. The CLI repository's own Discussions tab is enabled by the maintainers when ready; SUPPORT.md lists the current channels.
+  - name: Engine defect (parsing, writing, DEFLATE, CRC, Zip64)
+    url: https://github.com/Nizoka/zipnative/issues/new/choose
+    about: The CLI contains no ZIP logic of its own. A wrong byte, a wrong verdict or a ZIP_* code raised on a valid archive is an engine issue; the CLI ships the fixed engine in a patch release.
+  - name: AI agents drafting an issue
+    url: https://github.com/Nizoka/zipnative-cli/blob/main/.github/AGENT_RULES.md
+    about: Agents are draftsmen, never submitters. Run `zipnative govern verify-issue <draft.md>` and hand the draft to a human who submits it under their own identity.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,37 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement for zipnative-cli
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+<!-- Before filing: check ROADMAP.md and the core's anti-goals first.
+     Encryption (read or write) in 1.x, other archive formats, multi-disk /
+     spanned archives, archive repair, and filesystem/network I/O inside the
+     engine are documented non-goals of the zipnative ecosystem — the CLI
+     cannot expose what the engine will not do. Features that belong in the
+     engine (new parsing behaviour, new codecs) are filed upstream in
+     zipnative; the CLI only wires them. -->
+
+## Problem
+
+<!-- What problem does this feature solve? What CLI workflow is currently painful? -->
+
+## Proposed Solution
+
+<!-- Describe the flag, command, or behavior you'd like.
+     Include example shell invocations to illustrate the UX. -->
+
+```bash
+# Example
+zipnative create src/ --output out.zip --new-flag value
+```
+
+## Alternatives Considered
+
+<!-- Any alternative approaches, workarounds, or existing tools you've considered? -->
+
+## Additional Context
+
+<!-- Examples, related issues, links to the zipnative API this would leverage -->

.github/ISSUE_TEMPLATE/interop_report.md

@@ -0,0 +1,44 @@
+---
+name: Interop report
+about: An archive zipnative-cli wrote that another tool rejects, or a real-world archive the CLI mishandles
+title: '[interop] '
+labels: interop
+assignees: ''
+---
+
+## Direction
+
+- [ ] zipnative-cli **wrote** an archive that another tool rejects
+- [ ] Another tool **wrote** an archive that zipnative-cli mishandles
+
+## The other tool
+
+Name and **exact version** (e.g. `unzip 6.00`, `7-Zip 24.08`, `Windows 11 Explorer`,
+`macOS 15 Archive Utility`, `bsdtar 3.7.4`, `Temurin 21 jar`, `Python 3.12 zipfile`):
+
+## The CLI command
+
+```bash
+# Exact zipnative-cli invocation (create / modify / extract / stream …) and version
+zipnative --version
+```
+
+## Evidence
+
+- Error/output from the other tool:
+- `zipnative verify --input <a.zip> --format json` output:
+- `zipnative inspect --input <a.zip> --format json --entries` output (paste the
+  `diagnostics` array in full — `ZIP_*` diagnostic codes are the first clue):
+- Archive attached (as a .zip inside a .zip so GitHub keeps the bytes intact),
+  or a generator script, or a `7z l -slt <a.zip>` dump:
+
+## Producer
+
+If the archive came from a real-world producer (Word, a build tool, a phone),
+name it — the interop corpus grows from these reports.
+
+<!-- Note: the CLI contains no ZIP parsing logic — every byte-level operation
+     is a zipnative call. When triage shows the root cause is in the engine
+     (a header the reader misparses, bytes the writer emits), the issue is
+     re-filed upstream in zipnative and this one is linked to it; the CLI
+     tracks the fix through its dependency bump. -->

.github/ISSUE_TEMPLATE/maintenance.md

@@ -0,0 +1,41 @@
+---
+name: Maintenance / Chore
+about: Release tasks, dependency updates, metadata, documentation sync, governance
+title: 'chore: '
+labels: chore
+assignees: ''
+---
+
+## Type
+
+<!-- Release / Dependency bump / Metadata / Documentation / Governance / Infrastructure -->
+
+## Motivation
+
+<!-- Why is this work needed now? Link to ROADMAP item, zipnative parent release, audit finding, etc. -->
+
+## Scope
+
+<!-- What is explicitly included. What is explicitly excluded. Keep scope tight. -->
+
+### Included
+
+-
+
+### Excluded
+
+-
+
+## Acceptance Criteria
+
+<!-- Verifiable checklist. Each item should be objectively checkable. -->
+
+- [ ]
+- [ ]
+- [ ]
+
+## References
+
+<!-- Related issues, PRs, standards, ROADMAP items, zipnative upstream release -->
+
+-