Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,24 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- run: python3 scripts/package.py
- name: Read canonical app commit
id: source
run: |
python3 - <<'PYCODE' >> "$GITHUB_OUTPUT"
import json, re
sha = json.load(open("plugins/hitkeep-analytics/source.json"))["commit"]
assert re.fullmatch(r"[0-9a-f]{40}", sha)
print("sha=" + sha)
PYCODE
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
repository: HitKeep/hitkeep
ref: ${{ steps.source.outputs.sha }}
path: .canonical-app
persist-credentials: false
- run: python3 scripts/package.py --verify-source .canonical-app --source-sha "${{ steps.source.outputs.sha }}"
- run: python3 -m unittest discover -s tests
- run: python3 scripts/package.py --output /tmp/hitkeep-analytics.zip
- run: python3 scripts/package.py --output /tmp/hitkeep-analytics-again.zip
- run: cmp /tmp/hitkeep-analytics.zip /tmp/hitkeep-analytics-again.zip
- run: unzip -t /tmp/hitkeep-analytics.zip
65 changes: 65 additions & 0 deletions .github/workflows/sync-hitkeep-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
name: Sync verified HitKeep release
on:
workflow_dispatch:
inputs:
release_tag:
description: Published stable app tag (vX.Y.Z)
required: true
type: string
source_sha:
description: Exact app source commit
required: true
type: string
package_sha256:
description: Attested assistant ZIP SHA-256
required: true
type: string

permissions:
contents: read

concurrency:
group: sync-hitkeep-release
cancel-in-progress: false
queue: max

env:
RELEASE_TAG: ${{ inputs.release_tag }}
SOURCE_SHA: ${{ inputs.source_sha }}
PACKAGE_SHA256: ${{ inputs.package_sha256 }}
GIT_TERMINAL_PROMPT: '0'

jobs:
verify:
if: github.repository == 'HitKeep/hitkeep-assistant-plugins' && github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
permissions:
contents: read
attestations: read
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- name: Verify public candidate, producer attempt and canonical package
env:
GH_TOKEN: ${{ github.token }}
run: python3 scripts/release_delivery.py verify --release-tag "$RELEASE_TAG" --source-sha "$SOURCE_SHA" --package-sha256 "$PACKAGE_SHA256"

publish:
needs: verify
runs-on: ubuntu-latest
permissions:
contents: write
attestations: read
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
with:
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- name: Reverify, fast-forward generated files and publish immutable native ref
env:
GH_TOKEN: ${{ github.token }}
run: python3 scripts/release_delivery.py publish --release-tag "$RELEASE_TAG" --source-sha "$SOURCE_SHA" --package-sha256 "$PACKAGE_SHA256"
33 changes: 28 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ codex plugin marketplace add HitKeep/hitkeep-assistant-plugins
codex plugin add hitkeep-analytics@hitkeep
```

Start a new session, then invoke `$hitkeep-analytics` or another bundled skill. To pin the marketplace to this release, add it with `--ref v2.15.0`.
Start a new session, then invoke `$hitkeep-analytics` or another bundled skill. To pin the marketplace to a published release, add it with `--ref vX.Y.Z` (for example `--ref v2.15.0` for the existing historical release).

## ChatGPT

Where native archive upload is available:

1. Download [`hitkeep-analytics-2.15.0.zip`](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/download/v2.15.0/hitkeep-analytics-2.15.0.zip) from the [release](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/tag/v2.15.0).
1. Select a [published app release](https://github.com/HitKeep/hitkeep/releases) and download its `hitkeep-analytics-X.Y.Z.zip`. The corresponding [assistant release](https://github.com/HitKeep/hitkeep-assistant-plugins/releases) links the same verified ZIP. The existing [2.15.0 archive](https://github.com/HitKeep/hitkeep-assistant-plugins/releases/download/v2.15.0/hitkeep-analytics-2.15.0.zip) remains available in its original location.
2. Open **Settings → Plugins → Browse catalog → Add → Upload plugin archive** and select the ZIP, then select **Add plugin**.
3. Review **HitKeep Analytics**, version **2.15.0**, and its five skills, then select **Install plugin**.
3. Review **HitKeep Analytics**, the selected version, and its five skills, then select **Install plugin**.
4. Use **Try in chat** to start with the installed plugin.

This route was verified in signed-in ChatGPT web: the native plugin detail displayed version `2.15.0`, read capability, all five skills, and the installed **Manage** and **Try in chat** actions. It creates a private install, separate from public directory publication.
Expand All @@ -58,7 +58,7 @@ Follow the [HitKeep MCP guide](https://hitkeep.com/guides/integrations/mcp/) for

The MCP surface is read-only and aggregate-only. These skills cannot configure sites, change goals, export raw hits, manage tokens, or perform billing or administration. Skill installation never expands the authenticated user's authority.

Package version `2.15.0` identifies this skill distribution. OAuth availability depends on the deployed HitKeep version and configuration; publishing this package does not release or deploy the HitKeep application.
The package version identifies the skill distribution and its matching immutable Git tag. OAuth availability depends on the deployed HitKeep version and configuration; publishing this package does not release or deploy the HitKeep application.

## Verify and package

Expand All @@ -72,6 +72,29 @@ python3 scripts/package.py --output dist/hitkeep-analytics-2.15.0.zip

The verifier checks both native catalogs, matching manifest identities and versions, the exact skill allowlist, and every canonical file hash. The ZIP contains one plugin directory with both native manifests and the same skills; it has deterministic file order, timestamps, and permissions.

For an update, export only the five skill directories and `LICENSE` from the next reviewed commit of `HitKeep/hitkeep`, update their hashes and commit in `source.json`, and update both manifest versions and the Claude catalog version together. Keep `skills/` in the application repository canonical; changes to analytics instructions belong there first. Do not publish test fixtures or add credentials to a package.
For an update, check out an immutable reviewed app commit, then use the existing packager:

```sh
python3 scripts/package.py --sync-from ../hitkeep --source-sha FULL_APP_COMMIT --version X.Y.Z
python3 scripts/package.py --verify-source ../hitkeep --source-sha FULL_APP_COMMIT
```

Sync reads committed Git objects, stages and verifies all generated files before replacement, and records the app and packager commits in `source.json`. It copies exactly the five product skills' `SKILL.md`, `references/procedure.md`, and `agents/openai.yaml` files plus `LICENSE`; contributor `.agents/skills/` content never enters the package. Both native manifests and the Claude catalog advance together; the OpenAI catalog retains its native schema. CI independently retrieves the recorded app commit and compares bytes, so rewriting a local inventory cannot authorize changed skills. Keep application `skills/` canonical; analytics instruction changes belong there first. Ask AI continues to consume only the product procedure references.

## Release delivery and recovery

The application release builds the assistant ZIP once from an exact app commit using an immutable reviewed packager commit and records its digest in the attested release candidate. This repository receives exactly `release_tag`, `source_sha`, and `package_sha256` through `sync-hitkeep-release.yml` on main. GitHub authorizes the native dispatch; the receiver independently verifies the public stable app release, unchanged tag, candidate signature, exact producer run and attempt, mandatory checks, package digest, native manifests, and upstream skill bytes. Downloaded files are treated as data and never executed.

A read-only verification job must pass before the separate job receives its repository-scoped `GITHUB_TOKEN` write permission. The writer verifies again, rechecks current main and repository policy, and fast-forwards only the generated plugin, catalogs, and license. The workflow currently requires unprotected main and no repository or inherited rulesets; a policy change stops delivery for maintainer review. It never bypasses protection or force-pushes.

Each version has an immutable native installation ref `vX.Y.Z` and an assistant release linking the app ZIP. The assistant release uploads no second archive. Newer versions advance main and the native catalogs; backports receive only their historical tag and linked release, preserving newer catalogs and latest. Existing `v2.15.0` assets and refs remain unchanged.

To recover a partially completed delivery:

1. Open the failed native receiver run and rerun its failed jobs. The receiver revalidates inputs and current remote state, then resumes after a completed main update, tag, or release. Matching retries write nothing; conflicting immutable content stops for investigation. A canceled or failed caller watch does not cancel or prove failure of the receiver: inspect the exact receiver run first.
2. For a core app channel failure, use the app's native publication workflow with its original candidate run, attempt, and channel. Native reruns include dependent leaf jobs; an expired candidate requires a newly validated candidate. A successful assistant or other leaf need not be rolled back because another channel failed.
3. Resolve an explicit authentication or protection error before retrying. The receiver does not widen permissions, replace tags/assets, or downgrade a channel to make a retry pass. If main changed during a write race, the non-forced push fails; a native retry reads and validates the new head.

The run summary records the source/tag/digest, output ref and main readback, and whether delivery advanced main or created a historical ref. A native installation proves client packaging only; authenticated read-only aggregate MCP access still requires the separate connection described above. Private docs and cloud deployment follow their own authorized workflows.

MIT licensed; see [LICENSE](LICENSE).
121 changes: 118 additions & 3 deletions scripts/package.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
from pathlib import Path
import re
import zipfile
import os
import shutil
import subprocess
import tempfile

ROOT = Path(__file__).resolve().parents[1]
NAME = "hitkeep-analytics"
Expand All @@ -15,11 +19,104 @@
"hitkeep-ecommerce-analyst", "hitkeep-tracking-verifier",
}

CANONICAL = {f"skills/{name}/{part}" for name in SKILLS for part in (
"SKILL.md", "references/procedure.md", "agents/openai.yaml"
)} | {"LICENSE"}
GENERATED = {f"plugins/{NAME}/{path}" for path in CANONICAL | {
"plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md"
}} | {"LICENSE", ".claude-plugin/marketplace.json", ".agents/plugins/marketplace.json"}


def git(root, *args):
result = subprocess.run(["git", "-C", str(root), *args], capture_output=True)
if result.returncode:
raise ValueError("cannot read immutable Git source")
return result.stdout


def canonical(source_root, source_commit):
if not re.fullmatch(r"[0-9a-f]{40}", source_commit):
raise ValueError("source SHA must be a full immutable commit")
if git(source_root, "rev-parse", source_commit + "^{commit}").decode().strip() != source_commit:
raise ValueError("source SHA is not a commit")
result = {}
for relative in sorted(CANONICAL):
entry = git(source_root, "ls-tree", source_commit, "--", relative).decode().strip()
if not entry.startswith("100644 blob ") or entry.split("\t")[-1] != relative:
raise ValueError(f"canonical source must be a regular non-executable file: {relative}")
result[relative] = git(source_root, "show", f"{source_commit}:{relative}")
return result


def verify_source(source_root: Path, source_commit: str, root: Path = ROOT) -> None:
verify(root)
plugin = root / "plugins" / NAME
inventory = json.loads((plugin / "source.json").read_text())
if inventory["commit"] != source_commit:
raise ValueError("upstream source commit mismatch")
if "packager_commit" in inventory and not re.fullmatch(r"[0-9a-f]{40}", inventory["packager_commit"]):
raise ValueError("packager commit must be immutable")
for relative, data in canonical(source_root, source_commit).items():
if (plugin / relative).read_bytes() != data:
raise ValueError(f"upstream content mismatch: {relative}")
if (root / "LICENSE").read_bytes() != (plugin / "LICENSE").read_bytes():
raise ValueError("upstream content mismatch: root LICENSE")


def write_json(path, value):
path.write_text(json.dumps(value, indent=2) + "\n")


def sync(source_root: Path, source_commit: str, version: str, root: Path = ROOT) -> None:
if not re.fullmatch(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", version):
raise ValueError("invalid release version")
root = Path(root)
if root.is_symlink():
raise ValueError("symlink in output root")
root = root.resolve()
for relative in GENERATED:
path = root / relative
if any(parent.is_symlink() for parent in (path, *path.parents)):
raise ValueError("symlink in output path")
verify(root)
files = canonical(source_root, source_commit)
packager_commit = git(ROOT, "rev-parse", "HEAD").decode().strip()
# Stage and verify the entire generated tree before replacing any output.
with tempfile.TemporaryDirectory(prefix=".hitkeep-package-", dir=root.parent) as temp:
stage = Path(temp)
for name in ("plugins", ".claude-plugin", ".agents"):
shutil.copytree(root / name, stage / name)
plugin = stage / "plugins" / NAME
for relative, data in files.items():
(plugin / relative).write_bytes(data)
(stage / "LICENSE").write_bytes(files["LICENSE"])
for relative in ("plugin.json", ".claude-plugin/plugin.json"):
path = plugin / relative
manifest = json.loads(path.read_text())
manifest["version"] = version
write_json(path, manifest)
path = stage / ".claude-plugin/marketplace.json"
catalog = json.loads(path.read_text())
catalog["plugins"][0]["version"] = version
write_json(path, catalog)
write_json(plugin / "source.json", {
"repository": "https://github.com/HitKeep/hitkeep", "commit": source_commit,
"packager_commit": packager_commit,
"sha256": {path: hashlib.sha256(data).hexdigest() for path, data in files.items()},
})
verify_source(source_root, source_commit, stage)
for relative in sorted(GENERATED):
os.replace(stage / relative, root / relative)


def verify(root=ROOT):
plugin = root / "plugins" / NAME
if plugin.is_symlink():
raise ValueError("symlink in package root")
portable = json.loads((plugin / "plugin.json").read_text())
claude = json.loads((plugin / ".claude-plugin/plugin.json").read_text())
if set(portable) != {"$schema", "name", "version", "description", "author", "license", "extensions"} or set(claude) != {"name", "version", "description", "author", "license", "skills"}:
raise ValueError("unexpected native manifest fields or hooks")
version = portable["version"]
if not re.fullmatch(r"\d+\.\d+\.\d+", version):
raise ValueError("invalid release version")
Expand Down Expand Up @@ -54,17 +151,18 @@ def verify(root=ROOT):
raise ValueError("unexpected canonical source")
if not re.fullmatch(r"[0-9a-f]{40}", source["commit"]):
raise ValueError("canonical commit must be immutable")
expected = {f"skills/{name}/{part}" for name in SKILLS for part in (
"SKILL.md", "references/procedure.md", "agents/openai.yaml"
)} | {"LICENSE"}
expected = CANONICAL
if set(source["sha256"]) != expected:
raise ValueError("canonical source allowlist changed")
allowed = expected | {"plugin.json", ".claude-plugin/plugin.json", "source.json", "README.md"}
allowed_dirs = {parent.as_posix() for relative in allowed for parent in Path(relative).parents if parent != Path(".")}
actual = set()
for path in plugin.rglob("*"):
if path.is_symlink():
raise ValueError(f"symlink in package: {path}")
if path.is_dir():
if path.relative_to(plugin).as_posix() not in allowed_dirs:
raise ValueError("package directory allowlist mismatch")
continue
relative = path.relative_to(plugin).as_posix()
if not path.is_file() or path.stat().st_mode & 0o111:
Expand Down Expand Up @@ -95,6 +193,23 @@ def package(output, root=ROOT):
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--output", type=Path, help="write the verified plugin ZIP")
modes = parser.add_mutually_exclusive_group()
modes.add_argument("--sync-from", type=Path)
modes.add_argument("--verify-source", type=Path)
parser.add_argument("--source-sha")
parser.add_argument("--version")
args = parser.parse_args()
if (args.sync_from or args.verify_source) and not args.source_sha:
parser.error("source mode requires --source-sha")
if args.sync_from and not args.version:
parser.error("--sync-from requires --version")
if args.version and not args.sync_from:
parser.error("--version requires --sync-from")
if args.source_sha and not (args.sync_from or args.verify_source):
parser.error("--source-sha requires a source mode")
if args.sync_from:
sync(args.sync_from, args.source_sha, args.version, ROOT)
if args.verify_source:
verify_source(args.verify_source, args.source_sha, ROOT)
version = package(args.output) if args.output else verify()[0]
print(f"Verified {NAME} {version}: five canonical skills, two native manifests")
Loading
Loading