pi-free-catalog 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.

package/PUBLISHING-fa.md

@@ -1,6 +1,6 @@
 # انتشار در npm و نصب تک‌دستوری در Pi
 
-این بسته روی npm منتشر شده است: `pi-free-catalog` (بدون scope، نسخهٔ 0.1.1، نگهدارنده: `aminmza`). این راهنما برای انتشار نسخه‌های بعدی و بازتولید همین فرایند است. یک بسته هر دو provider را منتشر می‌کند؛ نیازی به انتشار دو بسته نیست.
+این بسته روی npm منتشر شده است: `pi-free-catalog` (بدون scope، نسخهٔ 0.1.2، نگهدارنده: `aminmza`). این راهنما برای انتشار نسخه‌های بعدی و بازتولید همین فرایند است. یک بسته هر دو provider را منتشر می‌کند؛ نیازی به انتشار دو بسته نیست.
 
 ## ۱. پیش‌نیاز
 
@@ -62,7 +62,7 @@ npm publish --access public
 برای بررسی پس از انتشار:
 
 ```bash
-npm view "pi-free-catalog@0.1.1" version dist.integrity dist.shasum
+npm view "pi-free-catalog@0.1.2" version dist.integrity dist.shasum
 ```
 
 ## ۵. نصب در Pi با یک دستور
@@ -70,13 +70,13 @@ npm view "pi-free-catalog@0.1.1" version dist.integrity dist.shasum
 برای همان حساب ناشر و در همان shell:
 
 ```bash
-pi install "npm:pi-free-catalog@0.1.1"
+pi install "npm:pi-free-catalog@0.1.2"
 ```
 
 برای دیگران، همان نام منتشرشده را بدهید:
 
 ```bash
-pi install npm:pi-free-catalog@0.1.1
+pi install npm:pi-free-catalog@0.1.2
 ```
 
 این نام واقعاً روی npm منتشر شده است. پس از نصب، Pi را دوباره اجرا کنید و providerهای `free-kilo` و `free-zen` را انتخاب کنید. npm بسته را نصب می‌کند؛ کاتالوگ مدل‌ها در هر اجرای خود افزونه از سرویس‌ها به‌روز می‌شود، نه از fixtureهای npm.
@@ -101,7 +101,7 @@ npm 12 انتشار را با «staged publishing» انجام می‌دهد و
 نکتهٔ مهم در محیط بدون TTY (Termux یا CI): کتابخانهٔ npm فقط زمانی جریان احراز هویت مرورگری را اجرا می‌کند که هر دو ورودی و خروجی TTY باشند؛ در غیر این صورت بی‌درنگ خطای `EOTP` می‌دهد. روی Termux از pty استفاده کنید:
 
 ```bash
-printf '\n' | script -qec 'npm publish ./pi-free-catalog-0.1.1.tgz --tag latest --access public' /dev/null
+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` را تغییر نمی‌دهد.
@@ -112,4 +112,4 @@ printf '\n' | script -qec 'npm publish ./pi-free-catalog-0.1.1.tgz --tag latest
 - https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification
 - https://docs.npmjs.com/trusted-publishers
 
-نسخهٔ فعلی منتشرشده `pi-free-catalog@0.1.1` است؛ نسخه‌های بعدی با همان حساب npm و 2FA منتشر می‌شوند. بررسی کد و مجوز MIT پیش از انتشار همچنان لازم است.
+نسخهٔ فعلی منتشرشده `pi-free-catalog@0.1.2` است؛ نسخه‌های بعدی با همان حساب npm و 2FA منتشر می‌شوند. بررسی کد و مجوز MIT پیش از انتشار همچنان لازم است.

package/README-fa.md

@@ -1,8 +1,8 @@
-# افزونهٔ زندهٔ مدل‌های رایگان Pi — نسخهٔ 0.1.1
+# افزونهٔ زندهٔ مدل‌های رایگان 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 با نام `pi-free-catalog` (نسخهٔ 0.1.1، مجوز MIT، نگهدارنده: `aminmza`). برای نصب از registry: `pi install npm:pi-free-catalog@0.1.1`
+**روی 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

package/README.md

@@ -18,7 +18,7 @@ There is no build step and no third-party runtime dependency beyond Pi's peer pa
 ## Install from npm
 
 ```bash
-pi install npm:pi-free-catalog@0.1.1
+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.
@@ -38,9 +38,9 @@ Pin the exact version for reproducibility. `pi -e npm:pi-free-catalog` loads the
 
 ## 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.
@@ -92,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. The packaging test accepts both `npm pack --json` output shapes (an array on npm 11, a name-keyed object on npm 12 and later).
+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):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-free-catalog",
-  "version": "0.1.1",
+  "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",

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()=>{