itch-jam-scout 0.2.0__tar.gz

itch_jam_scout-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcade Forge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

itch_jam_scout-0.2.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: itch-jam-scout
+Version: 0.2.0
+Summary: Read-only CLI that checks an itch.io jam's real phase, deadlines, and pool size from itch's own embedded JSON, instead of the page's countdown text.
+Author: Arcade Forge
+License: MIT
+Project-URL: Homepage, https://github.com/fernforge-arcade/itch-jam-scout
+Keywords: itch.io,game-jam,gamedev,cli
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# itch-jam-scout
+
+A read-only CLI that answers the two questions that actually matter before you
+enter an itch.io game jam: **what phase is it in right now**, and **how big is
+the pool you're competing in**.
+
+```
+pip install itch-jam-scout
+jam-scout trijam-379 codex-game-jam-2026
+```
+
+```json
+{
+  "url": "https://itch.io/jam/trijam-379",
+  "start_date": "2026-07-04 00:00:00",
+  "end_date": "2026-07-06 00:00:00",
+  "voting_end_date": "2026-07-13 00:00:00",
+  "phase": "voting open",
+  "rating_queue_disclosed": false,
+  "coverage_rule_disclosed": false,
+  "entry_count_hint": "28 entries"
+}
+```
+
+No `pip`? It's one file with zero dependencies — `python3 jam_scout.py <jam-slug>` works straight from a clone.
+
+## Why this exists
+
+itch jam pages show a countdown timer in the page header, and that timer is
+sometimes wrong — hosts extend deadlines after the page ships, and the
+human-readable text doesn't always get updated in step. The one place that
+can't lie is the `I.ViewJam(...)` JSON blob itch embeds in every jam page to
+drive its own countdown widget. This tool parses that blob directly instead
+of trusting the rendered text, so a moved deadline shows up correctly the
+first time you run it, not after you've already miscounted.
+
+It also surfaces the join/entry count where itch exposes it. That number
+matters more than people give it credit for: in a jam with 800 entries, your
+own rating activity is noise. In a jam with 20, it's a meaningful fraction of
+total votes — worth knowing before you decide where to spend a Saturday.
+
+## What it checks
+
+- **Phase** — not started / submissions open / voting open / closed, computed
+  against the jam's actual start/end/voting-end timestamps, not the countdown
+  text.
+- **Pool size** — join or entry count, when itch's page markup exposes it.
+- **Rating Queue mention** — whether the host's own jam description names
+  itch's Rating Queue system in text. This is a text search, not an API flag:
+  a `false` means "not mentioned on the page," not "confirmed off." Treat a
+  `true` as a real signal and a `false` as no signal either way.
+- **Coverage rule mention** — whether the page states a minimum number of
+  ratings you have to give or receive to count as a valid entry. Worth
+  checking because jam size alone doesn't predict how many entries actually
+  get rated: a 65-entry jam with no enforced minimum left 11 entries at zero
+  ratings, while a 485-entry jam with one rated 483 of them. In practice most
+  hosts don't put this in the page description even when it's true, so
+  expect `false` a lot — read it as "not stated here," not "doesn't exist."
+
+## What it doesn't do
+
+No login, no rating, no write actions of any kind — it fetches one public
+page and parses it. It can't tell you whether Rating Queue is toggled on for
+a jam that doesn't say so in its description; that toggle only becomes
+visible to logged-in entrants on the jam's own rate page, which is out of
+scope for something meant to run anonymously against any jam slug.
+
+## Usage
+
+```
+jam-scout <jam-slug> [<jam-slug> ...]
+jam-scout https://itch.io/jam/some-jam-2026
+```
+
+Or, without installing anything: `python3 jam_scout.py <jam-slug>`.
+
+Pass as many slugs or full URLs as you want; each prints its own JSON object.
+
+## Requirements
+
+Python 3.8+, standard library only. No dependencies to install.
+
+---
+
+Built autonomously by an AI agent as part of [Arcade Forge](https://fernforge.itch.io), an itch.io distribution experiment.

itch_jam_scout-0.2.0/README.md

@@ -0,0 +1,85 @@
+# itch-jam-scout
+
+A read-only CLI that answers the two questions that actually matter before you
+enter an itch.io game jam: **what phase is it in right now**, and **how big is
+the pool you're competing in**.
+
+```
+pip install itch-jam-scout
+jam-scout trijam-379 codex-game-jam-2026
+```
+
+```json
+{
+  "url": "https://itch.io/jam/trijam-379",
+  "start_date": "2026-07-04 00:00:00",
+  "end_date": "2026-07-06 00:00:00",
+  "voting_end_date": "2026-07-13 00:00:00",
+  "phase": "voting open",
+  "rating_queue_disclosed": false,
+  "coverage_rule_disclosed": false,
+  "entry_count_hint": "28 entries"
+}
+```
+
+No `pip`? It's one file with zero dependencies — `python3 jam_scout.py <jam-slug>` works straight from a clone.
+
+## Why this exists
+
+itch jam pages show a countdown timer in the page header, and that timer is
+sometimes wrong — hosts extend deadlines after the page ships, and the
+human-readable text doesn't always get updated in step. The one place that
+can't lie is the `I.ViewJam(...)` JSON blob itch embeds in every jam page to
+drive its own countdown widget. This tool parses that blob directly instead
+of trusting the rendered text, so a moved deadline shows up correctly the
+first time you run it, not after you've already miscounted.
+
+It also surfaces the join/entry count where itch exposes it. That number
+matters more than people give it credit for: in a jam with 800 entries, your
+own rating activity is noise. In a jam with 20, it's a meaningful fraction of
+total votes — worth knowing before you decide where to spend a Saturday.
+
+## What it checks
+
+- **Phase** — not started / submissions open / voting open / closed, computed
+  against the jam's actual start/end/voting-end timestamps, not the countdown
+  text.
+- **Pool size** — join or entry count, when itch's page markup exposes it.
+- **Rating Queue mention** — whether the host's own jam description names
+  itch's Rating Queue system in text. This is a text search, not an API flag:
+  a `false` means "not mentioned on the page," not "confirmed off." Treat a
+  `true` as a real signal and a `false` as no signal either way.
+- **Coverage rule mention** — whether the page states a minimum number of
+  ratings you have to give or receive to count as a valid entry. Worth
+  checking because jam size alone doesn't predict how many entries actually
+  get rated: a 65-entry jam with no enforced minimum left 11 entries at zero
+  ratings, while a 485-entry jam with one rated 483 of them. In practice most
+  hosts don't put this in the page description even when it's true, so
+  expect `false` a lot — read it as "not stated here," not "doesn't exist."
+
+## What it doesn't do
+
+No login, no rating, no write actions of any kind — it fetches one public
+page and parses it. It can't tell you whether Rating Queue is toggled on for
+a jam that doesn't say so in its description; that toggle only becomes
+visible to logged-in entrants on the jam's own rate page, which is out of
+scope for something meant to run anonymously against any jam slug.
+
+## Usage
+
+```
+jam-scout <jam-slug> [<jam-slug> ...]
+jam-scout https://itch.io/jam/some-jam-2026
+```
+
+Or, without installing anything: `python3 jam_scout.py <jam-slug>`.
+
+Pass as many slugs or full URLs as you want; each prints its own JSON object.
+
+## Requirements
+
+Python 3.8+, standard library only. No dependencies to install.
+
+---
+
+Built autonomously by an AI agent as part of [Arcade Forge](https://fernforge.itch.io), an itch.io distribution experiment.

itch_jam_scout-0.2.0/itch_jam_scout.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: itch-jam-scout
+Version: 0.2.0
+Summary: Read-only CLI that checks an itch.io jam's real phase, deadlines, and pool size from itch's own embedded JSON, instead of the page's countdown text.
+Author: Arcade Forge
+License: MIT
+Project-URL: Homepage, https://github.com/fernforge-arcade/itch-jam-scout
+Keywords: itch.io,game-jam,gamedev,cli
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# itch-jam-scout
+
+A read-only CLI that answers the two questions that actually matter before you
+enter an itch.io game jam: **what phase is it in right now**, and **how big is
+the pool you're competing in**.
+
+```
+pip install itch-jam-scout
+jam-scout trijam-379 codex-game-jam-2026
+```
+
+```json
+{
+  "url": "https://itch.io/jam/trijam-379",
+  "start_date": "2026-07-04 00:00:00",
+  "end_date": "2026-07-06 00:00:00",
+  "voting_end_date": "2026-07-13 00:00:00",
+  "phase": "voting open",
+  "rating_queue_disclosed": false,
+  "coverage_rule_disclosed": false,
+  "entry_count_hint": "28 entries"
+}
+```
+
+No `pip`? It's one file with zero dependencies — `python3 jam_scout.py <jam-slug>` works straight from a clone.
+
+## Why this exists
+
+itch jam pages show a countdown timer in the page header, and that timer is
+sometimes wrong — hosts extend deadlines after the page ships, and the
+human-readable text doesn't always get updated in step. The one place that
+can't lie is the `I.ViewJam(...)` JSON blob itch embeds in every jam page to
+drive its own countdown widget. This tool parses that blob directly instead
+of trusting the rendered text, so a moved deadline shows up correctly the
+first time you run it, not after you've already miscounted.
+
+It also surfaces the join/entry count where itch exposes it. That number
+matters more than people give it credit for: in a jam with 800 entries, your
+own rating activity is noise. In a jam with 20, it's a meaningful fraction of
+total votes — worth knowing before you decide where to spend a Saturday.
+
+## What it checks
+
+- **Phase** — not started / submissions open / voting open / closed, computed
+  against the jam's actual start/end/voting-end timestamps, not the countdown
+  text.
+- **Pool size** — join or entry count, when itch's page markup exposes it.
+- **Rating Queue mention** — whether the host's own jam description names
+  itch's Rating Queue system in text. This is a text search, not an API flag:
+  a `false` means "not mentioned on the page," not "confirmed off." Treat a
+  `true` as a real signal and a `false` as no signal either way.
+- **Coverage rule mention** — whether the page states a minimum number of
+  ratings you have to give or receive to count as a valid entry. Worth
+  checking because jam size alone doesn't predict how many entries actually
+  get rated: a 65-entry jam with no enforced minimum left 11 entries at zero
+  ratings, while a 485-entry jam with one rated 483 of them. In practice most
+  hosts don't put this in the page description even when it's true, so
+  expect `false` a lot — read it as "not stated here," not "doesn't exist."
+
+## What it doesn't do
+
+No login, no rating, no write actions of any kind — it fetches one public
+page and parses it. It can't tell you whether Rating Queue is toggled on for
+a jam that doesn't say so in its description; that toggle only becomes
+visible to logged-in entrants on the jam's own rate page, which is out of
+scope for something meant to run anonymously against any jam slug.
+
+## Usage
+
+```
+jam-scout <jam-slug> [<jam-slug> ...]
+jam-scout https://itch.io/jam/some-jam-2026
+```
+
+Or, without installing anything: `python3 jam_scout.py <jam-slug>`.
+
+Pass as many slugs or full URLs as you want; each prints its own JSON object.
+
+## Requirements
+
+Python 3.8+, standard library only. No dependencies to install.
+
+---
+
+Built autonomously by an AI agent as part of [Arcade Forge](https://fernforge.itch.io), an itch.io distribution experiment.

itch_jam_scout-0.2.0/itch_jam_scout.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+jam_scout.py
+pyproject.toml
+itch_jam_scout.egg-info/PKG-INFO
+itch_jam_scout.egg-info/SOURCES.txt
+itch_jam_scout.egg-info/dependency_links.txt
+itch_jam_scout.egg-info/entry_points.txt
+itch_jam_scout.egg-info/top_level.txt

itch_jam_scout-0.2.0/itch_jam_scout.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

itch_jam_scout-0.2.0/itch_jam_scout.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jam-scout = jam_scout:cli

itch_jam_scout-0.2.0/itch_jam_scout.egg-info/top_level.txt

@@ -0,0 +1 @@
+jam_scout

itch_jam_scout-0.2.0/jam_scout.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+jam_scout.py — screen an itch.io jam page for the visibility-algorithm axis
+(opportunity p-gje5aa: pick jams whose ranking mechanic rewards rating volume).
+
+Usage:
+    python3 jam_scout.py <jam-slug-or-url> [<jam-slug-or-url> ...]
+
+For each jam, fetches the public jam page and reports:
+  - submission/voting window (parsed from itch's embedded I.ViewJam JSON — the
+    only authoritative source; the human-readable countdown text has been wrong
+    on this jam before)
+  - current phase (submissions open / voting open / closed) as of now (UTC)
+  - whether the host's own description text names itch's Rating Queue system
+    (the fairness-floor mechanic — NOT a "rate more to be seen more" multiplier,
+    see memory/discovery-backlog.md) — this is host-disclosed, not an API flag,
+    so a false "no" just means "not verifiable from the page", not "absent"
+  - entry count, when the page exposes it, since a small pool is where an
+    agent's own rating activity is a bigger fraction of total votes
+  - whether the page states a minimum-ratings-to-unlock-results rule, since
+    real coverage data shows jam SIZE alone doesn't predict how many entries
+    get rated (a 65-entry jam left 11 entries at zero; a 485-entry jam with an
+    enforced rating requirement rated 483/485) — an explicit rule is a much
+    better signal than pool size
+
+No login, no rating, no write actions — read-only reconnaissance only.
+"""
+import sys
+import re
+import json
+import urllib.request
+from datetime import datetime, timezone
+
+UA = "Mozilla/5.0 ArcadeForge/1.0"
+
+
+def fetch(url):
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    with urllib.request.urlopen(req, timeout=20) as r:
+        return r.read().decode("utf-8", errors="replace")
+
+
+def normalize_url(arg):
+    if arg.startswith("http"):
+        return arg
+    return f"https://itch.io/jam/{arg}"
+
+
+def parse_view_jam(html):
+    m = re.search(r"I\.ViewJam\('#view_jam_\d+',\s*(\{.*?\})\)", html)
+    if not m:
+        return None
+    return json.loads(m.group(1))
+
+
+def parse_dt(s):
+    return datetime.strptime(s, "%Y-%m-%d %H:%M:%S").replace(tzinfo=timezone.utc)
+
+
+def phase(meta, now):
+    start = parse_dt(meta["start_date"])
+    end = parse_dt(meta["end_date"])
+    voting_end = meta.get("voting_end_date")
+    voting_end = parse_dt(voting_end) if voting_end else None
+    if now < start:
+        return "not started"
+    if now < end:
+        return "submissions open"
+    if voting_end and now < voting_end:
+        return "voting open"
+    return "closed"
+
+
+def rating_queue_signal(html):
+    return bool(re.search(r"rating queue", html, re.IGNORECASE))
+
+
+def coverage_rule_signal(html):
+    # Look for host-stated language requiring a minimum number of ratings
+    # given/received to unlock results or count as a valid entry. This is a
+    # weaker text-match than rating_queue_signal on purpose: hosts phrase it
+    # many ways ("rate at least 5 games", "minimum of 3 ratings to qualify").
+    # A False here means "not stated in the page text", not "does not exist" —
+    # some jams enforce this via a separate rules tab this tool doesn't fetch.
+    return bool(re.search(
+        r"(rate|review)\s+(at least|a minimum of|\d+)\s+\w*\s*(game|entr|submission)",
+        html, re.IGNORECASE,
+    ))
+
+
+def entry_count(html):
+    # itch shows a "Joined"/"Entries" stat pair in stat_box widgets; entries only
+    # appears once submissions have closed, so "Joined" is the best pre-close proxy
+    # for pool size (bigger pool = your own ratings move the needle less).
+    stats = {label: value for value, label in re.findall(
+        r'stat_value">(\d+)</div><div class="stat_label">([^<]+)', html)}
+    for label in ("Entries", "Submissions", "Joined"):
+        if label in stats:
+            return f"{stats[label]} {label.lower()}"
+    m = re.search(r'([\d,]+)\s+(?:entries|submissions|games)\b', html, re.IGNORECASE)
+    if m:
+        return m.group(1)
+    return None
+
+
+def scout(arg, now=None):
+    url = normalize_url(arg)
+    now = now or datetime.now(timezone.utc)
+    html = fetch(url)
+    meta = parse_view_jam(html)
+    result = {"url": url}
+    if meta is None:
+        result["error"] = "no I.ViewJam block found (page shape changed or not a jam page)"
+        return result
+    result["start_date"] = meta.get("start_date")
+    result["end_date"] = meta.get("end_date")
+    result["voting_end_date"] = meta.get("voting_end_date")
+    result["phase"] = phase(meta, now)
+    result["rating_queue_disclosed"] = rating_queue_signal(html)
+    result["coverage_rule_disclosed"] = coverage_rule_signal(html)
+    result["entry_count_hint"] = entry_count(html)
+    return result
+
+
+def main(argv):
+    if len(argv) < 2:
+        print(__doc__)
+        return 1
+    for arg in argv[1:]:
+        r = scout(arg)
+        print(json.dumps(r, indent=2))
+    return 0
+
+
+def cli():
+    sys.exit(main(sys.argv))
+
+
+if __name__ == "__main__":
+    cli()

itch_jam_scout-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "itch-jam-scout"
+version = "0.2.0"
+description = "Read-only CLI that checks an itch.io jam's real phase, deadlines, and pool size from itch's own embedded JSON, instead of the page's countdown text."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Arcade Forge" }]
+keywords = ["itch.io", "game-jam", "gamedev", "cli"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+]
+
+[project.urls]
+Homepage = "https://github.com/fernforge-arcade/itch-jam-scout"
+
+[project.scripts]
+jam-scout = "jam_scout:cli"
+
+[tool.setuptools]
+py-modules = ["jam_scout"]

itch_jam_scout-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+