Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,22 @@ On mismatch, **lockfile v3** also explains *what* changed with a deterministic f

Spec: [SPEC.md](./SPEC.md) (Lockfile Spec v1.4; canonicalization `surfacepin-jcs-v1` + lockfile v1/v2/v3).

## 60-second start
## Quick start

Node 20+. From a clone, `npm install` once, then `npm run demo`. The demo builds and runs the CLI on committed fixtures only (no network, no API keys).

```bash
git clone https://github.com/yellowgram/surfacepin.git
cd surfacepin
npm install
npm run demo
```

`npm run demo` proves exact-hash lockfile verify on committed fixtures (`testdata/basic.tools.json` against `basic.v3.lock.json`, and multi-surface `basic.surface.json`) and that a one-character description drift fails verify. Pass/fail is digest equality. `HINT_FLIP` is a field-diff label, not a safety verdict.

```bash
# Node 20+
npm install -g surfacepin # or: npx surfacepin … / npm install surfacepin --save-dev
# Installed package: npm install -g surfacepin
# or: npx surfacepin … / npm install surfacepin --save-dev

# Lock (writes lockfile v3 with embedded surfaces for structured diff)
surfacepin lock tools.json -o surfacepin.lock.json
Expand Down Expand Up @@ -70,8 +81,9 @@ Machine output: `surfacepin diff … --json`.

### Local from this repo

`npm run demo` is the fixture proof above (`npm install` first; the script builds). Unit tests and other local CLI checks:

```bash
npm install
npm test
node dist/cli.js lock examples/tools.json -o /tmp/sp.lock.json
node dist/cli.js lock testdata/basic.surface.json --surface tools,resources,prompts -o /tmp/sp-multi.lock.json
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"scripts": {
"build": "tsc -p tsconfig.json",
"test": "npm run build && node --test dist/test/*.test.js",
"demo": "npm run build && node scripts/demo.mjs",
"prepublishOnly": "npm run build"
},
"keywords": [
Expand Down
159 changes: 159 additions & 0 deletions scripts/demo.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
#!/usr/bin/env node
/**
* Sealed demo. Committed fixtures only: no network, no API keys, no live MCP.
*
* 1. verify testdata/basic.tools.json against testdata/basic.v3.lock.json
* 2. verify testdata/basic.surface.json against testdata/basic.multi.lock.json
* 3. lock both fixtures and require the bytes to match those lockfiles
* 4. one-character description drift of basic.tools.json must fail verify
* and print a COMPATIBLE field-diff (pass/fail stays digest equality)
*
* Exit 0 only when all of the above hold.
*/
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";

const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const cli = join(root, "dist", "cli.js");
const testdata = join(root, "testdata");

const toolsPath = join(testdata, "basic.tools.json");
const toolsLockPath = join(testdata, "basic.v3.lock.json");
const surfacePath = join(testdata, "basic.surface.json");
const multiLockPath = join(testdata, "basic.multi.lock.json");

function rel(path) {
return path.startsWith(root) ? path.slice(root.length + 1) : path;
}

function run(args, expect) {
const shown = args.map((a) => rel(a)).join(" ");
console.log(`\n$ surfacepin ${shown}`);
const r = spawnSync(process.execPath, [cli, ...args], {
encoding: "utf8",
cwd: root,
});
if (r.error) {
console.error(`demo: failed to run CLI: ${r.error.message}`);
process.exit(1);
}
if (r.stdout) process.stdout.write(r.stdout);
if (r.stderr) process.stderr.write(r.stderr);
const code = r.status === null ? 2 : r.status;
if (code !== expect) {
console.error(`demo: expected exit ${expect}, got ${code}`);
process.exit(1);
}
return r.stdout ?? "";
}

function readJson(path) {
return JSON.parse(readFileSync(path, "utf8"));
}

function assertSameLock(actualPath, goldenPath) {
try {
assert.deepEqual(readJson(actualPath), readJson(goldenPath));
} catch {
console.error(
`demo: lock ${rel(actualPath)} does not match ${rel(goldenPath)}`,
);
process.exit(1);
}
console.log(`lock matches ${rel(goldenPath)}`);
}

console.log("surfacepin demo — committed fixtures only (no network)");

const toolsOk = run(["verify", toolsPath, toolsLockPath], 0);
if (!toolsOk.includes("OK: surface matches lockfile")) {
console.error("demo: tools verify did not report a match");
process.exit(1);
}

const multiOk = run(
[
"verify",
surfacePath,
multiLockPath,
"--surface",
"tools,resources,prompts",
],
0,
);
if (!multiOk.includes("OK: surface matches lockfile")) {
console.error("demo: multi-surface verify did not report a match");
process.exit(1);
}

const dir = mkdtempSync(join(tmpdir(), "surfacepin-demo-"));
try {
const lockedTools = join(dir, "basic.v3.lock.json");
const lockedMulti = join(dir, "basic.multi.lock.json");

run(["lock", toolsPath, "-o", lockedTools], 0);
assertSameLock(lockedTools, toolsLockPath);
run(["verify", toolsPath, lockedTools], 0);

run(
[
"lock",
surfacePath,
"--surface",
"tools,resources,prompts",
"-o",
lockedMulti,
],
0,
);
assertSameLock(lockedMulti, multiLockPath);
run(
[
"verify",
surfacePath,
lockedMulti,
"--surface",
"tools,resources,prompts",
],
0,
);

const doc = readJson(toolsPath);
const before = doc.tools?.[0]?.description;
if (typeof before !== "string" || before.length === 0) {
console.error("demo: basic.tools.json has no tools[0].description");
process.exit(1);
}
doc.tools[0].description = `${before}.`;
const driftedPath = join(dir, "basic.drift.tools.json");
writeFileSync(driftedPath, `${JSON.stringify(doc, null, 2)}\n`);

console.log(
`\n# one-character drift of testdata/basic.tools.json ("${before}" -> "${before}.")`,
);
const diffOut = run(["diff", driftedPath, toolsLockPath], 1);
if (!diffOut.includes("DRIFT: surface does not match lockfile")) {
console.error("demo: drift diff did not report DRIFT");
process.exit(1);
}
if (!diffOut.includes("CHANGED description (COMPATIBLE)")) {
console.error("demo: drift diff did not report COMPATIBLE description change");
process.exit(1);
}

const verifyDrift = run(["verify", driftedPath, toolsLockPath], 1);
if (!verifyDrift.includes("DRIFT: surface does not match lockfile")) {
console.error("demo: drift verify did not fail closed");
process.exit(1);
}
} finally {
rmSync(dir, { recursive: true, force: true });
}

console.log(
"\ndemo ok: exact-hash match on committed fixtures; one-character drift failed closed",
);
Loading