stilltrue 0.4.1 → 0.5.1

package/README.md

@@ -36,33 +36,60 @@ project folder with your facts saved in a JSON file.
 npm install --save-dev stilltrue
 ```
 
-**2. Describe a check** — create a file called `stilltrue.config.mjs` in
-the same folder. Each check answers three questions: *where do I fetch the
-truth from* (`source`), *what do I believe* (`expect`), and *how do I
-compare the two* (`compare`):
+**2. Scaffold a check** — this creates a ready-to-edit config file (it
+never overwrites anything you already have):
+
+```bash
+npx stilltrue init
+```
+
+Open the generated `stilltrue.config.mjs`. Each check answers three
+questions: *where do I fetch the truth from* (`source`), *what do I
+believe* (`expect`), and *how do I compare the two* (`compare`) — and in
+its simplest form, **the only editing needed is replacing strings**:
 
 ```js
-import { defineStilltrue, corpus, json, surname } from 'stilltrue';
+import { defineStilltrue, corpus } from 'stilltrue';
 
 export default defineStilltrue({
   drift: [
     {
-      name: 'school-board-roster',
-      // Where the truth lives: the district's own pages.
-      source: corpus(['https://www.myschooldistrict.org/board']),
-      // What you believe: read your saved file, keep just the last names.
-      expect: json('./data/school-board.json', (data) =>
-        data.members.map((m) => surname(m.name))
-      ),
-      // How to compare: every name must still appear on those pages.
+      name: 'my-first-check',
+      // Where the truth lives: the official page(s) your facts came from.
+      source: corpus(['https://example.org/about']),
+      // What you believe: your facts, as short strings ("markers").
+      expect: ['Jane Smith', 'Main Street Office', '12 locations'],
+      // How to compare: every marker must still appear on those pages.
       compare: 'contains-all',
     },
   ],
 });
 ```
 
-This example says: *fetch the board page, and make sure every last name in
-my `school-board.json` file still appears somewhere on it.*
+This says: *fetch that page, and make sure "Jane Smith", "Main Street
+Office", and "12 locations" all still appear on it.* Swap in your own URL
+and your own facts — that's a working check, no programming required.
+
+Choosing what to assert is the judgment call — surnames beat full names,
+"143 schools" beats a bare "143". The short guide:
+[docs/MARKERS.md](docs/MARKERS.md).
+
+**Leveling up (optional):** you don't have to keep the facts in the config.
+If `./data/markers.json` is just a list of strings, point at it with
+`expect: json('./data/markers.json')` — still no code. And if your app
+already keeps structured data, derive the markers from it so your data file
+stays the single source of truth:
+
+```js
+// ./data/school-board.json: { "members": [{ "name": "Dr. Jane Smith" }, ...] }
+expect: json('./data/school-board.json', (data) =>
+  data.members.map((m) => surname(m.name))   // keeps just "Smith" — titles
+),                                           // and first names vary on pages
+```
+
+The function receives *your* file's contents, whatever shape they are, and
+returns the list of markers — stilltrue never needs to understand your data
+structure. Update the data file and the markers update themselves.
 
 **3. Run it:**
 

package/dist/cli.js

@@ -94,13 +94,31 @@ try {
         case 'report':
             process.exit(await report(rest));
             break;
+        case 'init': {
+            const { init } = await import("./init.js");
+            const { created, skipped } = await init(process.cwd());
+            for (const f of created)
+                console.log(`created ${f}`);
+            for (const f of skipped)
+                console.log(`kept existing ${f} (never overwritten)`);
+            if (created.length) {
+                console.log('\nNext steps:\n' +
+                    '  1. Edit stilltrue.config.mjs — point source at the real page(s) your facts came from,\n' +
+                    '     and replace the example markers with your own facts (plain strings)\n' +
+                    '  2. Run: npx stilltrue drift\n' +
+                    'Picking good markers: docs/MARKERS.md in the stilltrue repo');
+            }
+            process.exit(0);
+            break;
+        }
         case 'golden':
             console.error('stilltrue deliberately has no golden runner — promptfoo tests your prompts; stilltrue tests your facts.\n' +
                 'Use https://promptfoo.dev for prompt/answer regression evals. Doctrine + pairing guide: docs/GOLDEN.md');
             process.exit(1);
             break;
         default:
-            console.log('usage: stilltrue drift [--config <path>] [--only <names>] [--json <path>] [--record] [--history <path>]\n' +
+            console.log('usage: stilltrue init\n' +
+                '       stilltrue drift [--config <path>] [--only <names>] [--json <path>] [--record] [--history <path>]\n' +
                 '       stilltrue report [--history <path>] [--out <path>] [--title <text>]');
             process.exit(command ? 1 : 0);
     }

package/dist/init.d.ts

@@ -0,0 +1,6 @@
+export interface InitResult {
+    created: string[];
+    skipped: string[];
+}
+/** Write the starter config. Never overwrites an existing one. */
+export declare function init(dir: string): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,72 @@
+import { writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const CONFIG_TEMPLATE = `// stilltrue configuration — one entry per fact-set you want watched.
+// Docs: https://github.com/sg-bfoster/stilltrue#readme
+// Picking good markers: https://github.com/sg-bfoster/stilltrue/blob/main/docs/MARKERS.md
+import { defineStilltrue, corpus, json, surname } from 'stilltrue';
+
+export default defineStilltrue({
+  drift: [
+    {
+      // A short id for this check — shows up in output and reports.
+      name: 'my-first-check',
+
+      // WHERE THE TRUTH LIVES: the official page(s) your facts came from.
+      // corpus() fetches each page and strips it down to readable text.
+      source: corpus([
+        'https://example.org/about',
+        // 'https://example.org/board',   // add more pages if facts span several
+      ]),
+
+      // WHAT YOU BELIEVE: list the facts as short strings ("markers").
+      // Every one of these must still appear somewhere on the page(s)
+      // above, or the check fails and names the missing one.
+      expect: [
+        'Jane Smith',
+        'Main Street Office',
+        '12 locations',
+      ],
+
+      // HOW TO COMPARE: 'contains-all' = every marker must appear in the
+      // fetched page text (case-insensitive).
+      compare: 'contains-all',
+    },
+
+    // ── Leveling up (optional) ──────────────────────────────────────────
+    //
+    // Instead of listing markers inline, you can keep them in a file.
+    // If ./data/markers.json contains just a list of strings —
+    //   ["Jane Smith", "Main Street Office", "12 locations"]
+    // — then this works with no code at all:
+    //
+    //   expect: json('./data/markers.json'),
+    //
+    // And if your app already keeps structured data — say
+    // ./data/board.json looks like
+    //   { "members": [ { "name": "Dr. Jane Smith" }, { "name": "Bob Jones Jr." } ] }
+    // — you can derive the markers from it, so your data file stays the
+    // single source of truth (surname() keeps just "Smith" / "Jones",
+    // because pages change titles and first names more than surnames):
+    //
+    //   expect: json('./data/board.json', (data) =>
+    //     data.members.map((m) => surname(m.name))
+    //   ),
+  ],
+});
+`;
+/** Write the starter config. Never overwrites an existing one. */
+export async function init(dir) {
+    const existingConfig = [
+        'stilltrue.config.mjs',
+        'stilltrue.config.ts',
+        'stilltrue.config.mts',
+        'stilltrue.config.js',
+        'stilltrue.config.cjs',
+    ].find((name) => existsSync(join(dir, name)));
+    if (existingConfig) {
+        return { created: [], skipped: [existingConfig] };
+    }
+    await writeFile(join(dir, 'stilltrue.config.mjs'), CONFIG_TEMPLATE);
+    return { created: ['stilltrue.config.mjs'], skipped: [] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stilltrue",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Your tests check your code. stilltrue checks your facts. CI checks for AI-in-the-loop apps: drift (curated facts vs live sources), golden (regression evals), verify (judge answers against sources).",
   "keywords": [
     "drift",