stilltrue 0.4.1 → 0.5.0

package/README.md

@@ -36,10 +36,16 @@ 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 and an
+example facts 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`):
 
 ```js
 import { defineStilltrue, corpus, json, surname } from 'stilltrue';
@@ -64,6 +70,10 @@ export default defineStilltrue({
 This example says: *fetch the board page, and make sure every last name in
 my `school-board.json` file still appears somewhere on it.*
 
+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).
+
 **3. Run it:**
 
 ```bash

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' +
+                    '  2. Edit data/example-facts.json — or point the config at a facts file you already have\n' +
+                    '  3. 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 starter config + example data file. Never overwrites. */
+export declare function init(dir: string): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,78 @@
+import { mkdir, 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: 'example-board-roster',
+
+      // WHERE THE TRUTH LIVES: the official page(s) your facts came from.
+      // corpus() fetches each page and strips it down to readable text.
+      // If one page is unreachable it warns; only if ALL are down does the
+      // check report an error (which never fails your build).
+      source: corpus([
+        'https://example.org/board',
+        // 'https://example.org/about',   // add more pages if facts span several
+      ]),
+
+      // WHAT YOU BELIEVE: read your saved facts file and pick out the
+      // "markers" — short, stable strings that must still appear on the
+      // page(s) above. Here: each member's last name, plus one number.
+      expect: json('./data/example-facts.json', (data) => [
+        ...data.members.map((m) => surname(m.name)),
+        \`\${data.totalSchools} schools\`,
+      ]),
+
+      // HOW TO COMPARE: 'contains-all' = every marker must appear in the
+      // fetched text (case-insensitive). Any missing marker = rot = the
+      // build fails and tells you which fact went stale.
+      compare: 'contains-all',
+    },
+  ],
+});
+`;
+const DATA_TEMPLATE = `{
+  "_comment": "Example facts file - replace with your own data, or point the config at a file you already have.",
+  "members": [
+    { "name": "Dr. Jane Smith" },
+    { "name": "Robert Jones Jr." }
+  ],
+  "totalSchools": 12
+}
+`;
+/** Write starter config + example data file. Never overwrites. */
+export async function init(dir) {
+    const created = [];
+    const skipped = [];
+    const configPath = join(dir, 'stilltrue.config.mjs');
+    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) {
+        skipped.push(existingConfig);
+    }
+    else {
+        await writeFile(configPath, CONFIG_TEMPLATE);
+        created.push('stilltrue.config.mjs');
+    }
+    const dataPath = join(dir, 'data', 'example-facts.json');
+    if (existsSync(dataPath)) {
+        skipped.push('data/example-facts.json');
+    }
+    else {
+        await mkdir(join(dir, 'data'), { recursive: true });
+        await writeFile(dataPath, DATA_TEMPLATE);
+        created.push('data/example-facts.json');
+    }
+    return { created, skipped };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stilltrue",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",