pi-free-catalog 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.1.0 — 2026-10-17 — local, unpublished
+## 0.1.2 — 2026-10-17
+
+- Storage: the saved catalog state is now gzipped and compact instead of pretty-printed. On a real catalog this is ~27 MB → ~1.3 MB (about 95% smaller), cutting startup load time and the bytes rewritten on every refresh. `load()` accepts gzipped state and plain JSON, so pre-0.1.2 catalogs still load unchanged.
+- Fixed: `atomicJSON` wrote machine-read state with 2-space indentation, roughly doubling the file for no benefit. Indentation remains off for the catalog; user-facing exports (`/free-export`, `scripts/catalog.mjs`) stay readable plain JSON.
+- Tests: added a regression test asserting the saved state is gzip-magic, far smaller than pretty JSON, round-trips through `load()`, and that a legacy plain-JSON cache still loads.
+
+## 0.1.1 — 2026-10-17
+
+- Public npm release of the unscoped package `pi-free-catalog` (MIT), superseding 0.1.0.
+- Fixed: `test/package.test.mjs` assumed `npm pack --json` returns an array. npm 12 returns an object keyed by package name, so the assertion threw. It now accepts both shapes, which means `prepublishOnly` verification passes on npm 11 and npm 12.
+- Docs: removed the false "has not been published / provisional name" statements from README.md, README-fa.md and PUBLISHING-fa.md; install instructions now reference the real published name and version.
+- package.json: added `author`; host-provided peer packages now use the `"*"` range prescribed by Pi's `docs/packages.md`.
+
+## 0.1.0 — 2026-10-17 — first published release
 
 - New independent dual-provider extension, free-kilo + free-zen.
 - Await all five live catalog/price/capability sources on every load.

package/PUBLISHING-fa.md

@@ -1,6 +1,6 @@
 # انتشار در npm و نصب تک‌دستوری در Pi
 
-این بسته هنوز منتشر نشده است. هیچ نام npm بدون scope برای شما رزرو نشده و هیچ login/publish واقعی انجام نشده است. یک بسته هر دو provider را منتشر می‌کند؛ نیازی به انتشار دو بسته نیست.
+این بسته روی npm منتشر شده است: `pi-free-catalog` (بدون scope، نسخهٔ 0.1.2، نگهدارنده: `aminmza`). این راهنما برای انتشار نسخه‌های بعدی و بازتولید همین فرایند است. یک بسته هر دو provider را منتشر می‌کند؛ نیازی به انتشار دو بسته نیست.
 
 ## ۱. پیش‌نیاز
 
@@ -11,7 +11,7 @@
 
 طبق مستندات فعلی npm، انتشار بسته به 2FA یا روش مجاز token نیاز دارد. پیشنهاد این راهنما **login و انتشار تعاملی با 2FA** است. رمز، OTP، توکن یا فایل `.npmrc` را در چت/سورس نگذارید. برای CI در آینده trusted publishing را بررسی کنید، نه قراردادن توکن در کد.
 
-## ۲. نام بسته را به scope خودتان تغییر دهید
+## ۲. نام و scope بسته
 
 داخل پوشهٔ استخراج‌شده:
 
@@ -23,7 +23,7 @@ npm login
 npm whoami
 ```
 
-پس از login، این دو خط نام بسته را از نام موقت به scope حساب واقعی شما تغییر می‌دهد:
+این بسته بدون scope منتشر شده است و نیازی به تغییر نام ندارد. فقط اگر می‌خواهید نسخهٔ خودتان را با scope منتشر کنید، نام را عوض کنید:
 
 ```bash
 NPM_USER="$(npm whoami)"
@@ -62,7 +62,7 @@ npm publish --access public
 برای بررسی پس از انتشار:
 
 ```bash
-npm view "@${NPM_USER}/pi-free-catalog@0.1.0" version dist.integrity
+npm view "pi-free-catalog@0.1.2" version dist.integrity dist.shasum
 ```
 
 ## ۵. نصب در Pi با یک دستور
@@ -70,16 +70,16 @@ npm view "@${NPM_USER}/pi-free-catalog@0.1.0" version dist.integrity
 برای همان حساب ناشر و در همان shell:
 
 ```bash
-pi install "npm:@${NPM_USER}/pi-free-catalog@0.1.0"
+pi install "npm:pi-free-catalog@0.1.2"
 ```
 
-برای دیگران، فرمان نهایی را با نام واقعی scope منتشر کنید؛ مثلاً اگر حساب شما `myname` باشد:
+برای دیگران، همان نام منتشرشده را بدهید:
 
 ```bash
-pi install npm:@myname/pi-free-catalog@0.1.0
+pi install npm:pi-free-catalog@0.1.2
 ```
 
-`myname` در مثال، جایگزین است و ادعای وجود بسته‌ای با این نام نیست. پس از نصب، Pi را دوباره اجرا کنید و providerهای `free-kilo` و `free-zen` را انتخاب کنید. npm بسته را نصب می‌کند؛ کاتالوگ مدل‌ها در هر اجرای خود افزونه از سرویس‌ها به‌روز می‌شود، نه از fixtureهای npm.
+این نام واقعاً روی npm منتشر شده است. پس از نصب، Pi را دوباره اجرا کنید و providerهای `free-kilo` و `free-zen` را انتخاب کنید. npm بسته را نصب می‌کند؛ کاتالوگ مدل‌ها در هر اجرای خود افزونه از سرویس‌ها به‌روز می‌شود، نه از fixtureهای npm.
 
 ## ۶. نسخهٔ بعدی
 
@@ -94,10 +94,22 @@ npm publish --access public
 
 تغییرات و سازگاری را در CHANGELOG ثبت کنید. اگر نسخهٔ جدید User-Agent/README نسخهٔ محصول را تغییر می‌دهد، آن برچسب‌ها را هم هماهنگ کنید. از افزایش جعلی نسخهٔ پروتکل سازگاری برای پنهان‌کردن خطای API استفاده نکنید؛ سازگاری را واقعاً تست کنید.
 
+## ۷. نکتهٔ عملی: 2FA و انتشار مرحله‌ای در npm 12
+
+npm 12 انتشار را با «staged publishing» انجام می‌دهد و اثبات حضور (2FA) را به مرحله‌ای بعد موکول می‌کند؛ خانوادهٔ دستورهای `npm stage publish|list|view|approve|reject` برای همین کار است.
+
+نکتهٔ مهم در محیط بدون TTY (Termux یا CI): کتابخانهٔ npm فقط زمانی جریان احراز هویت مرورگری را اجرا می‌کند که هر دو ورودی و خروجی TTY باشند؛ در غیر این صورت بی‌درنگ خطای `EOTP` می‌دهد. روی Termux از pty استفاده کنید:
+
+```bash
+printf '\n' | script -qec 'npm publish ./pi-free-catalog-0.1.2.tgz --tag latest --access public' /dev/null
+```
+
+سپس URL چاپ‌شده را در مرورگر تأیید کنید. ممکن است npm یک نسخهٔ جایگزین `0.0.0-stage` (stub) هم در registry بسازد؛ این نسخهٔ خالی است و برچسب `latest` را تغییر نمی‌دهد.
+
 ## مستندات رسمی بررسی‌شده
 
 - https://docs.npmjs.com/cli/v11/commands/npm-publish
 - https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification
 - https://docs.npmjs.com/trusted-publishers
 
-هیچ ورود به حساب npm یا انتشار عمومی انجام نشده است؛ این تحویل، آماده‌سازی سورس و بستهٔ قابل انتشار است، نه ادعای انتشار عمومی.
+نسخهٔ فعلی منتشرشده `pi-free-catalog@0.1.2` است؛ نسخه‌های بعدی با همان حساب npm و 2FA منتشر می‌شوند. بررسی کد و مجوز MIT پیش از انتشار همچنان لازم است.

package/README-fa.md

@@ -1,8 +1,8 @@
-# افزونهٔ زندهٔ مدل‌های رایگان Pi — نسخهٔ 0.1.0
+# افزونهٔ زندهٔ مدل‌های رایگان Pi — نسخهٔ 0.1.2
 
 یک بسته با دو provider مستقل: **`free-kilo`** و **`free-zen`**. پیاده‌سازی مستقل است؛ افزونهٔ رسمی Kilo/OpenCode نیست. روی **Pi 1.3.0 و Node 22.23.3** آزمایش شده؛ حداقل Node اعلام‌شده **22.19** است. نسخه‌های قدیمی Pi تضمین نمی‌شوند.
 
-**هنوز روی npm منتشر نشده است.** نام بدون scope صرفاً نام محلی بسته است؛ برای انتشار، از نام آزاد یا scope متعلق به خودتان استفاده کنید.
+**روی npm منتشر شده است:** بستهٔ بدون scope با نام `pi-free-catalog` (نسخهٔ 0.1.2، مجوز MIT، نگهدارنده: `aminmza`). برای نصب از registry: `pi install npm:pi-free-catalog@0.1.2`
 
 ## نصب محلی
 
@@ -30,7 +30,7 @@ pi
 
 ## همهٔ اطلاعات چه زمانی تازه می‌شود؟
 
-در شروع، درخواست‌ها موازی و با timeout دوازده‌ثانیه‌ای برای هر منبع ارسال می‌شوند. بدنه‌ها حداکثر ۱۶ MiB هستند. بدنهٔ خام منابع، مشخصات، قیمت، قابلیت‌ها، وضعیت و زمان دریافت در فایل زیر ذخیره می‌شود:
+در شروع، درخواست‌ها موازی و با timeout دوازده‌ثانیه‌ای برای هر منبع ارسال می‌شوند. بدنه‌ها حداکثر ۱۶ MiB هستند. بدنهٔ خام منابع، مشخصات، قیمت، قابلیت‌ها، وضعیت و زمان دریافت در فایل زیر ذخیره می‌شود (فشرده با gzip و بدون تو رفتگی؛ حدود ۱ تا ۲ مگابایت):
 
 ```text
 ~/.pi/agent/free-catalog/catalog.json
@@ -124,4 +124,4 @@ node scripts/catalog.mjs /tmp/free-catalog-live.json
 
 اسکریپت‌های `scripts/live_pi.py`، `scripts/observe_live.py` و recorder محافظ `scripts/wire.mjs` نیز همراه سورس هستند. اجرای آن‌ها اختیاری و نیازمند Python 3، Pi نصب‌شده و مسیرهای `PI_NODE`، `PI_CLI`، `PI_TEST_DISPATCHER` و `FREE_TEST_DIR` است. ابتدا snapshot را با `catalog.mjs` در `FREE_TEST_DIR/live-catalog.json` بنویسید. توضیح دقیق‌تر در README انگلیسی آمده است. داده‌های این آزمون‌ها فقط fixture محلی‌اند؛ آن‌ها را روی پوشهٔ پروژه/اطلاعات محرمانهٔ خود اجرا نکنید. نتیجهٔ هر مدل را از JSON بخوانید؛ خروج موفق اسکریپت به معنی موفقیت همهٔ مدل‌های upstream نیست.
 
-گزارش اجرای واقعی این نسخه و فایل شواهد، جدا از بستهٔ قابل انتشار تحویل شده‌اند. دستور انتشار در **PUBLISHING-fa.md** است؛ انتشار واقعی انجام نشده و به حساب خودتان نیاز دارد.
+گزارش اجرای واقعی این نسخه و فایل شواهد، جدا از بستهٔ قابل انتشار تحویل شده‌اند. روند انتشار نسخه‌های بعدی در **PUBLISHING-fa.md** آمده است؛ انتشار از حساب npm نگهدارنده با 2FA انجام می‌شود.

package/README.md

@@ -1,6 +1,6 @@
 # pi-free-catalog
 
-Live, auditable **anonymous Kilo + OpenCode Zen** model discovery for **Pi 1.3.x / Node >=22.19**. One Pi package, two separate providers: `free-kilo` and `free-zen`. This package is an independent integration, not an official service client. **This source release has not been published to npm by its authoring assistant.** The unscoped name is provisional; publish under your own available name/scope.
+Live, auditable **anonymous Kilo + OpenCode Zen** model discovery for **Pi 1.3.x / Node >=22.19**. One Pi package, two separate providers: `free-kilo` and `free-zen`. This package is an independent integration, not an official service client. It is published on npm as [`pi-free-catalog`](https://www.npmjs.com/package/pi-free-catalog) under the MIT license, maintained by `aminmza`.
 
 [فارسی](README-fa.md) · [Publishing instructions](PUBLISHING-fa.md)
 
@@ -15,7 +15,13 @@ pi
 
 There is no build step and no third-party runtime dependency beyond Pi's peer packages. Do not `npm install -g` this as a standalone agent. Choose `free-kilo` or `free-zen` in Pi's model picker. You do not need a personal API key, login or OpenCode CLI process. Disable other extensions modifying these requests when diagnosing conflicts.
 
-Once YOU publish, installation becomes `pi install npm:@YOUR_USERNAME/pi-free-catalog@0.1.0` (replace the username). That example is not an existing published-package claim.
+## Install from npm
+
+```bash
+pi install npm:pi-free-catalog@0.1.2
+```
+
+Pin the exact version for reproducibility. `pi -e npm:pi-free-catalog` loads the package for a single invocation without changing your settings.
 
 ## Non-negotiable: no silent omissions
 
@@ -32,9 +38,9 @@ Once YOU publish, installation becomes `pi install npm:@YOUR_USERNAME/pi-free-ca
 
 ## Refresh, history and retirement
 
-Startup awaits bounded parallel source requests (12-second timeout per source, 16 MiB per body). Full raw JSON, exact IDs, metadata, source timestamps, classification and lifecycle history are saved under `<Pi agent directory>/free-catalog/catalog.json`. Normal location: `~/.pi/agent/free-catalog/`.
+Startup awaits bounded parallel source requests (12-second timeout per source, 16 MiB per body). Full raw JSON, exact IDs, metadata, source timestamps, classification and lifecycle history are saved under `<Pi agent directory>/free-catalog/catalog.json` (gzip-compressed, compact; roughly 1–2 MB for a live catalog). Normal location: `~/.pi/agent/free-catalog/`.
 
-After five minutes, the next agent turn/request revalidates. `/free-refresh` explicitly fetches everything immediately. No permanent background timer. History retains every seen ID; the recent transition event log is bounded to 2,000 events, not the ID inventory.
+After five minutes, the next agent turn/request revalidates. `/free-refresh` explicitly fetches everything immediately. No permanent background timer. History retains every seen ID; the recent transition event log is bounded to 2,000 events, not the ID inventory. The file's size is dominated by the retained raw per-source payloads that make offline evidence and failure fallback possible, not by history; it is bounded by the upstream catalog size and does not grow on repeated refreshes.
 
 - Explicit upstream retirement / elapsed explicit retirement date: retired, removed from callable models, retained in history.
 - Missing from a successful catalog: **not-listed**, NOT proven retired; removed from callable models, retained in history. Reappearance restores it automatically.
@@ -86,7 +92,7 @@ npm install
 npm run verify
 ```
 
-Verification runs syntax checks, offline automated tests against compressed real catalog fixtures (2026-10-17), mocked lifecycle/transport/security tests, real Pi SDK stream/classifier normalization tests, and npm package-content inspection. These are **not live inference claims**. Peer SDK 1.3.0 was used; fixture expectations do not pin the production catalog.
+Verification runs syntax checks, offline automated tests against compressed real catalog fixtures (2026-10-17), mocked lifecycle/transport/security tests, real Pi SDK stream/classifier normalization tests, and npm package-content inspection. These are **not live inference claims**. Peer SDK 1.3.0 was used; fixture expectations do not pin the production catalog. The packaging test accepts both `npm pack --json` output shapes (an array on npm 11, a name-keyed object on npm 12 and later). A storage test asserts the saved state stays gzip-compressed and compact, round-trips, and that a pre-0.1.2 plain-JSON cache still loads.
 
 Opt-in live catalog inspection (network, no inference):
 
@@ -96,7 +102,7 @@ node scripts/catalog.mjs /tmp/free-catalog-live.json
 
 Opt-in real Pi CLI tests are in `scripts/live_pi.py` and `scripts/observe_live.py` (Python 3 + Node + installed Pi peer packages). Set absolute `PI_NODE`, `PI_CLI`, `PI_TEST_DISPATCHER`, and `FREE_TEST_DIR`; generate `FREE_TEST_DIR/live-catalog.json` with `catalog.mjs` first. `PI_TEST_DISPATCHER` is Pi's installed `dist/core/http-dispatcher.js`. `PI_CLI` is its `dist/cli.js`. The separate test-only `wire.mjs` enforces a confirmed-free allowlist and 120 POST attempts/service, records request payloads/HTTP statuses, and is never loaded in production. The suite uses isolated HOME/settings, random fixtures, default tools ON and strict named read/write/edit/bash verification. It exits processes on deadlines. Inspect `inference-results.json`; process exit 0 alone does not mean all upstream models passed. Re-running reuses completed case IDs; use a new evidence directory for a fresh complete run.
 
-Publishing requires your own npm identity/permissions. See [PUBLISHING-fa.md](PUBLISHING-fa.md). Never share npm tokens or commit `.npmrc`, credentials, caches or live test files.
+Releases are published from the `aminmza` npm account with 2FA enabled. See [PUBLISHING-fa.md](PUBLISHING-fa.md). Never share npm tokens or commit `.npmrc`, credentials, caches or live test files.
 
 ## Sources
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "pi-free-catalog",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Live, auditable anonymous Kilo and OpenCode free model catalogs for Pi. No name-based free filtering.",
   "type": "module",
   "license": "MIT",
+  "author": "Amin Mozaffari <aminmozaffari1185@gmail.com>",
   "keywords": [
     "pi-package",
     "pi",
@@ -15,8 +16,8 @@
     "node": ">=22.19.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=1.3.0 <2",
-    "@earendil-works/pi-coding-agent": ">=1.3.0 <2"
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
   },
   "pi": {
     "extensions": [

package/src/catalog.js

@@ -1,4 +1,5 @@
 import { readFile, mkdir, writeFile, rename } from 'node:fs/promises';
+import { gzipSync, gunzipSync } from 'node:zlib';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
@@ -145,11 +146,14 @@ export function summary(state) {
   }
   return result;
 }
-export async function atomicJSON(file, data) {
+export async function atomicJSON(file, data, {gzip=false}={}) {
   await mkdir(dirname(file),{recursive:true,mode:0o700});
   const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
-  await writeFile(temp,JSON.stringify(data,null,2),{mode:0o600}); await rename(temp,file);
+  // Compact when gzipping: indentation is pure waste for machine-read state.
+  const body = gzip ? gzipSync(JSON.stringify(data)) : JSON.stringify(data,null,2);
+  await writeFile(temp,body,{mode:0o600}); await rename(temp,file);
 }
+export const isGzip = (buf) => buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b;
 export class Catalog {
   constructor({file,fetch:fetcher=globalThis.fetch,timeout=12000,now=()=>Date.now(),maxAge=300000}={}) {
     this.file=file;this.fetcher=fetcher;this.timeout=timeout;this.now=now;this.maxAge=maxAge;this.state={schemaVersion:1,sources:{},entries:{},history:[]};this.lastAttempt=0;
@@ -157,7 +161,10 @@ export class Catalog {
   async load() {
     if (!this.file) return;
     try {
-      const state=JSON.parse(await readFile(this.file,'utf8'));
+      // Accepts gzipped state (current) and plain JSON (pre-0.1.2 catalogs).
+      const buf=await readFile(this.file);
+      const text=isGzip(buf)?gunzipSync(buf).toString('utf8'):buf.toString('utf8');
+      const state=JSON.parse(text);
       if (state.schemaVersion===1 && state.entries && state.sources) this.state=state;
     } catch(error) { if(error.code!=='ENOENT') this.cacheWarning=String(error); }
   }
@@ -184,7 +191,7 @@ export class Catalog {
     // Never let Pi's startup refresh cancellation invalidate a successful startup snapshot.
     if(signal?.aborted){this.lastAttempt=previousAttempt;throw signal.reason || new Error('Catalog refresh cancelled');}
     this.state=reconcile(sources,old,new Date(this.now()).toISOString());
-    if(this.file) try{await atomicJSON(this.file,this.state);}catch(e){this.cacheWarning=String(e);}
+    if(this.file) try{await atomicJSON(this.file,this.state,{gzip:true});}catch(e){this.cacheWarning=String(e);}
     return this.state;
   }
   async ensureFresh() { if(this.now()-this.lastAttempt>=this.maxAge) await this.refresh(); }

package/test/catalog.test.mjs

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
+import { gunzipSync } from 'node:zlib';
 import { join } from 'node:path';
 import { Catalog, reconcile, recordKey, summary, priceClass, validateSource } from '../src/catalog.js';
 import { registrations, report } from '../src/models.js';
@@ -93,7 +94,23 @@ test('startup load is followed by new network calls, updates saved cache, concur
  const fetch=async(...a)=>{calls++;return fetcher()(...a);};
  const a=new Catalog({file,fetch});await a.refresh();assert.equal(calls,5);
  const b=new Catalog({file,fetch});await b.load();await Promise.all([b.refresh(),b.refresh()]);assert.equal(calls,10);
- assert.equal(JSON.parse(await readFile(file,'utf8')).schemaVersion,1);assert.equal(summary(b.state).kilo.free,17);
+ assert.equal(JSON.parse(gunzipSync(await readFile(file)).toString('utf8')).schemaVersion,1);assert.equal(summary(b.state).kilo.free,17);
+ }finally{await rm(dir,{recursive:true,force:true});}
+});
+test('saved state is gzipped and compact, round-trips, and legacy plain caches still load',async()=>{
+ const dir=await mkdtemp(join(tmpdir(),'pi-free-gz-'));try{
+ const file=join(dir,'catalog.json');
+ const a=new Catalog({file,fetch:fetcher()});await a.refresh();
+ const raw=await readFile(file);
+ assert.equal(raw[0],0x1f);assert.equal(raw[1],0x8b);
+ const parsed=JSON.parse(gunzipSync(raw).toString('utf8'));assert.equal(parsed.schemaVersion,1);
+ const pretty=Buffer.byteLength(JSON.stringify(parsed,null,2));
+ assert.ok(raw.length*3<pretty,`gzipped ${raw.length} should be far below pretty ${pretty}`);
+ const b=new Catalog({file,fetch:fetcher()});await b.load();
+ assert.equal(summary(b.state).kilo.free,17);
+ assert.equal(Object.keys(b.state.entries).length,Object.keys(parsed.entries).length);
+ const legacy=join(dir,'legacy.json');await writeFile(legacy,JSON.stringify(parsed,null,2));
+ const c=new Catalog({file:legacy,fetch:fetcher()});await c.load();assert.equal(summary(c.state).kilo.free,17);
  }finally{await rm(dir,{recursive:true,force:true});}
 });
 test('fresh paid price beats stale free source and blocks dispatch',async()=>{